diff --git a/.clippy.toml b/.clippy.toml
new file mode 100644
index 0000000..eb12f60
--- /dev/null
+++ b/.clippy.toml
@@ -0,0 +1,4 @@
+# Clippy configuration
+doc-valid-idents = ["GitHub", "GitLab", "TypeScript", "WebSocket", "PostgreSQL", "Redis", "OpenAI"]
+avoid-breaking-exported-api = true
+disallowed-types = []
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..0b8cf0b
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,42 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{js,ts,jsx,tsx,json,jsonc,md,yaml,yml,toml}]
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.go]
+indent_style = tab
+indent_size = unset
+tab_width = 8
+[*.rs]
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+indent_size = unset
+
+[Dockerfile]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.toml]
+indent_style = space
+indent_size = 2
\ No newline at end of file
diff --git a/app/email/Cargo.toml b/app/email/Cargo.toml
new file mode 100644
index 0000000..280815a
--- /dev/null
+++ b/app/email/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "app-email"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[[bin]]
+name = "email-service"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = { workspace = true }
+config = { workspace = true }
+email = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter", "json"] }
+
+[lints]
+workspace = true
\ No newline at end of file
diff --git a/app/email/src/context.rs b/app/email/src/context.rs
new file mode 100644
index 0000000..5872453
--- /dev/null
+++ b/app/email/src/context.rs
@@ -0,0 +1,24 @@
+use config::AppConfig;
+use tracing_subscriber::EnvFilter;
+
+pub struct AppContext {
+    pub config: AppConfig,
+}
+
+impl AppContext {
+    pub fn init() -> anyhow::Result<Self> {
+        let config = AppConfig::load();
+        init_tracing(&config)?;
+        Ok(Self { config })
+    }
+}
+
+fn init_tracing(config: &AppConfig) -> anyhow::Result<()> {
+    let level = config.log_level()?;
+    let filter = EnvFilter::try_new(&level)?;
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .init();
+    Ok(())
+}
diff --git a/app/email/src/main.rs b/app/email/src/main.rs
new file mode 100644
index 0000000..50f7f01
--- /dev/null
+++ b/app/email/src/main.rs
@@ -0,0 +1,22 @@
+mod context;
+
+use context::AppContext;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let ctx = AppContext::init()?;
+    tracing::info!("email service starting");
+
+    tokio::select! {
+        result = email::EmailWorker::start(&ctx.config) => {
+            if let Err(e) = result {
+                tracing::error!("email worker exited with error: {}", e);
+            }
+        }
+        _ = tokio::signal::ctrl_c() => {
+            tracing::info!("shutdown signal received, stopping email service");
+        }
+    }
+
+    Ok(())
+}
diff --git a/app/gitdata/Cargo.toml b/app/gitdata/Cargo.toml
new file mode 100644
index 0000000..42696cf
--- /dev/null
+++ b/app/gitdata/Cargo.toml
@@ -0,0 +1,50 @@
+[package]
+name = "app-gitdata"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[[bin]]
+name = "gitdata"
+path = "src/main.rs"
+
+[[bin]]
+name = "gen-openapi"
+path = "src/bin/gen-openapi.rs"
+
+[dependencies]
+anyhow = { workspace = true }
+config = { workspace = true }
+cache = { workspace = true }
+db = { workspace = true }
+service = { workspace = true }
+session = { workspace = true }
+api = { workspace = true }
+email = { workspace = true }
+storage = { workspace = true }
+git = { workspace = true }
+model = { workspace = true }
+channel = { workspace = true }
+socketio = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter", "json"] }
+actix-web = { workspace = true, features = ["cookies", "secure-cookies"] }
+actix-ws = { workspace = true }
+tonic = { workspace = true, features = ["transport"] }
+deadpool-redis = { workspace = true }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp", "connection-manager", "cluster"] }
+sqlx = { workspace = true, features = ["postgres", "runtime-tokio"] }
+serde_json = { workspace = true }
+uuid = { workspace = true, features = ["v4", "v7", "serde"] }
+
+[lints]
+workspace = true
\ No newline at end of file
diff --git a/app/gitdata/src/bin/gen-openapi.rs b/app/gitdata/src/bin/gen-openapi.rs
new file mode 100644
index 0000000..8bc5c4c
--- /dev/null
+++ b/app/gitdata/src/bin/gen-openapi.rs
@@ -0,0 +1,7 @@
+use std::fs;
+
+fn main() {
+    let json = api::openapi::openapi_json();
+    fs::write("openapi.json", json).expect("Failed to write openapi.json");
+    println!("openapi.json generated successfully");
+}
diff --git a/app/gitdata/src/context.rs b/app/gitdata/src/context.rs
new file mode 100644
index 0000000..c4c9c58
--- /dev/null
+++ b/app/gitdata/src/context.rs
@@ -0,0 +1,127 @@
+use actix_web::cookie::Key;
+use cache::{AppCache, AppCacheConfig};
+use config::AppConfig;
+use db::database::AppDatabase;
+use deadpool_redis::{
+    PoolConfig, Runtime, Timeouts,
+    cluster::{Config, Pool as RedisPool},
+};
+use email::AppEmail;
+use service::AppService;
+use session::storage::RedisClusterSessionStore;
+use storage::{AppStorage, AppStorageConfig};
+use tonic::transport::Channel;
+
+use channel::{ChannelBus, ChannelBusConfig};
+use socketio::SocketIo;
+
+pub struct AppContext {
+    pub config: AppConfig,
+    pub service: AppService,
+    pub session_store: RedisClusterSessionStore,
+    pub session_key: Key,
+    pub channel_bus: ChannelBus,
+}
+
+impl AppContext {
+    pub async fn init() -> anyhow::Result<Self> {
+        let config = AppConfig::load();
+        init_tracing(&config)?;
+
+        tracing::info!("initializing database");
+        let db = AppDatabase::init(&config).await?;
+
+        tracing::info!("initializing cache");
+        let cache_config = AppCacheConfig::try_from(&config)?;
+        let cache = AppCache::init(cache_config).await?;
+
+        tracing::info!("initializing storage");
+        let storage_config = AppStorageConfig::try_from(&config)?;
+        let storage = AppStorage::init(storage_config).await?;
+
+        tracing::info!("initializing email");
+        let email = AppEmail::init(&config).await?;
+
+        tracing::info!("connecting to git RPC");
+        let rpc_addr = config.git_rpc_addr()?;
+        let rpc_port = config.git_rpc_port()?;
+        let git_channel =
+            Channel::from_shared(format!("http://{}:{}", rpc_addr, rpc_port))
+                .expect("invalid gRPC endpoint")
+                .connect()
+                .await?;
+
+        let service = AppService {
+            db,
+            cache,
+            email,
+            storage,
+            config: config.clone(),
+            git: git_channel,
+            redis_pool: init_redis_pool(&config)?,
+        };
+
+        tracing::info!("initializing session store");
+        let redis_urls = config.redis_urls()?;
+        let session_store = RedisClusterSessionStore::new(redis_urls).await?;
+
+        tracing::info!("initializing session key");
+        let secret = config.session_secret()?;
+        let session_key = Key::from(secret.as_bytes());
+
+        tracing::info!("initializing channel bus");
+        let io = SocketIo::new();
+        let channel_config = ChannelBusConfig {
+            namespace: "/channel".to_owned(),
+            signing_secret: Some(secret.clone()),
+            ..Default::default()
+        };
+        let channel_bus = ChannelBus::new(
+            service.db.clone(),
+            service.cache.clone(),
+            io,
+            channel_config,
+        );
+        channel_bus.attach().await?;
+
+        Ok(Self {
+            config,
+            service,
+            session_store,
+            session_key,
+            channel_bus,
+        })
+    }
+}
+
+fn init_tracing(config: &AppConfig) -> anyhow::Result<()> {
+    let level = config.log_level()?;
+    let filter = tracing_subscriber::EnvFilter::try_new(&level)?;
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .init();
+    Ok(())
+}
+
+fn init_redis_pool(config: &AppConfig) -> anyhow::Result<RedisPool> {
+    let redis_urls = config.redis_urls()?;
+    let pool_size = config.redis_pool_size()?;
+    let connect_timeout = config.redis_connect_timeout()?;
+    let acquire_timeout = config.redis_acquire_timeout()?;
+
+    let mut pool_config = PoolConfig::new(pool_size as usize);
+    pool_config.timeouts = Timeouts {
+        wait: Some(std::time::Duration::from_secs(acquire_timeout)),
+        create: Some(std::time::Duration::from_secs(connect_timeout)),
+        recycle: Some(std::time::Duration::from_secs(connect_timeout)),
+    };
+
+    let cfg = Config {
+        urls: Some(redis_urls),
+        connections: None,
+        pool: Some(pool_config),
+        read_from_replicas: false,
+    };
+    Ok(cfg.create_pool(Some(Runtime::Tokio1))?)
+}
diff --git a/app/gitdata/src/main.rs b/app/gitdata/src/main.rs
new file mode 100644
index 0000000..1c4ebae
--- /dev/null
+++ b/app/gitdata/src/main.rs
@@ -0,0 +1,111 @@
+mod context;
+mod shutdown;
+
+use std::time::Instant;
+
+use actix_web::{App, dev::Service};
+use context::AppContext;
+use service::ai::sync::spawn_model_sync_loop;
+
+const REQUEST_LOG_EXCLUDED_PATHS: &[&str] = &[
+    "/health",
+    "/live",
+    "/ready",
+    "/metrics",
+    "/favicon.ico",
+    "/robots.txt",
+];
+
+fn should_log_request(path: &str) -> bool {
+    !REQUEST_LOG_EXCLUDED_PATHS.contains(&path)
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let ctx = AppContext::init().await?;
+
+    let api_port = ctx.config.api_port()?;
+    tracing::info!("GitDataAI API service starting on 0.0.0.0:{}", api_port);
+
+    let service = ctx.service.clone();
+    let session_store = ctx.session_store.clone();
+    let session_key = ctx.session_key.clone();
+    let channel_bus = ctx.channel_bus.clone();
+
+    let srv = actix_web::HttpServer::new(move || {
+        let session_middleware = session::SessionMiddleware::builder(
+            session_store.clone(),
+            session_key.clone(),
+        )
+        .cookie_secure(false)
+        .cookie_name("id".to_string())
+        .session_lifecycle(
+            session::config::PersistentSession::default()
+                .session_ttl(actix_web::cookie::time::Duration::days(30)),
+        )
+        .build();
+
+        App::new()
+            .app_data(actix_web::web::Data::new(service.clone()))
+            .app_data(actix_web::web::Data::new(channel_bus.clone()))
+            .wrap_fn(|req, srv| {
+                let should_log = should_log_request(req.path());
+                let method = req.method().clone();
+                let path = req.path().to_owned();
+                let peer_addr =
+                    req.connection_info().peer_addr().map(str::to_owned);
+                let started_at = Instant::now();
+                let fut = srv.call(req);
+
+                async move {
+                    match fut.await {
+                        Ok(res) => {
+                            if should_log {
+                                tracing::info!(
+                                    method = %method,
+                                    path = %path,
+                                    status = res.status().as_u16(),
+                                    elapsed_ms = started_at.elapsed().as_millis(),
+                                    peer_addr = peer_addr.as_deref().unwrap_or("-"),
+                                    "http request"
+                                );
+                            }
+                            Ok(res)
+                        }
+                        Err(err) => {
+                            if should_log {
+                                tracing::warn!(
+                                    method = %method,
+                                    path = %path,
+                                    elapsed_ms = started_at.elapsed().as_millis(),
+                                    peer_addr = peer_addr.as_deref().unwrap_or("-"),
+                                    error = %err,
+                                    "http request failed"
+                                );
+                            }
+                            Err(err)
+                        }
+                    }
+                }
+            })
+            .wrap(session_middleware)
+            .configure(|cfg| api::configure(cfg, channel_bus.clone()))
+    })
+    .bind(format!("0.0.0.0:{}", api_port))?;
+
+    spawn_model_sync_loop(ctx.service.clone());
+
+    let server = srv.run();
+    tracing::info!("API server is running");
+
+    tokio::select! {
+        _ = server => {
+            tracing::info!("API server stopped");
+        }
+        _ = shutdown::wait_for_shutdown_signal() => {
+            tracing::info!("shutdown signal received, stopping gitdata API service");
+        }
+    }
+
+    Ok(())
+}
diff --git a/app/gitdata/src/shutdown.rs b/app/gitdata/src/shutdown.rs
new file mode 100644
index 0000000..fe10327
--- /dev/null
+++ b/app/gitdata/src/shutdown.rs
@@ -0,0 +1,25 @@
+pub async fn wait_for_shutdown_signal() {
+    let ctrl_c = async {
+        tokio::signal::ctrl_c()
+            .await
+            .expect("failed to listen for ctrl_c event");
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        tokio::signal::unix::signal(
+            tokio::signal::unix::SignalKind::terminate(),
+        )
+        .expect("failed to listen for SIGTERM")
+        .recv()
+        .await;
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        _ = ctrl_c => {},
+        _ = terminate => {},
+    }
+}
diff --git a/app/gitpod/Cargo.toml b/app/gitpod/Cargo.toml
new file mode 100644
index 0000000..e43b586
--- /dev/null
+++ b/app/gitpod/Cargo.toml
@@ -0,0 +1,32 @@
+[package]
+name = "app-gitpod"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[[bin]]
+name = "gitpod"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = { workspace = true }
+config = { workspace = true }
+cache = { workspace = true }
+db = { workspace = true }
+git = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter", "json"] }
+deadpool-redis = { workspace = true }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp"] }
+
+[lints]
+workspace = true
\ No newline at end of file
diff --git a/app/gitpod/src/context.rs b/app/gitpod/src/context.rs
new file mode 100644
index 0000000..45b5a8e
--- /dev/null
+++ b/app/gitpod/src/context.rs
@@ -0,0 +1,65 @@
+use std::time::Duration;
+
+use cache::{AppCache, AppCacheConfig};
+use config::AppConfig;
+use db::database::AppDatabase;
+use deadpool_redis::{PoolConfig, Runtime, Timeouts, cluster::Config};
+
+pub struct AppContext {
+    pub config: AppConfig,
+    pub db: AppDatabase,
+    pub cache: AppCache,
+    pub redis_pool: deadpool_redis::cluster::Pool,
+}
+
+impl AppContext {
+    pub async fn init() -> anyhow::Result<Self> {
+        let config = AppConfig::load();
+        init_tracing(&config)?;
+
+        tracing::info!("initializing database");
+        let db = AppDatabase::init(&config).await?;
+
+        tracing::info!("initializing cache");
+        let cache_config = AppCacheConfig::try_from(&config)?;
+        let cache = AppCache::init(cache_config).await?;
+
+        tracing::info!("initializing redis pool");
+        let redis_urls = config.redis_urls()?;
+        let pool_size = config.redis_pool_size()?;
+        let connect_timeout = config.redis_connect_timeout()?;
+        let acquire_timeout = config.redis_acquire_timeout()?;
+
+        let mut pool_config = PoolConfig::new(pool_size as usize);
+        pool_config.timeouts = Timeouts {
+            wait: Some(Duration::from_secs(acquire_timeout)),
+            create: Some(Duration::from_secs(connect_timeout)),
+            recycle: Some(Duration::from_secs(connect_timeout)),
+        };
+
+        let cfg = Config {
+            urls: Some(redis_urls),
+            connections: None,
+            pool: Some(pool_config),
+            read_from_replicas: false,
+        };
+        let redis_pool = cfg.create_pool(Some(Runtime::Tokio1))?;
+
+        Ok(Self {
+            config,
+            db,
+            cache,
+            redis_pool,
+        })
+    }
+}
+
+fn init_tracing(config: &AppConfig) -> anyhow::Result<()> {
+    let level = config.log_level()?;
+    let filter = tracing_subscriber::EnvFilter::try_new(&level)?;
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .init();
+    Ok(())
+}
diff --git a/app/gitpod/src/main.rs b/app/gitpod/src/main.rs
new file mode 100644
index 0000000..0b8bd62
--- /dev/null
+++ b/app/gitpod/src/main.rs
@@ -0,0 +1,82 @@
+mod context;
+mod shutdown;
+
+use context::AppContext;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let ctx = AppContext::init().await?;
+
+    let http_port = ctx.config.git_http_port()?;
+    let ssh_port = ctx.config.ssh_port()?;
+    let rpc_addr = ctx.config.git_rpc_addr()?;
+    let rpc_port = ctx.config.git_rpc_port()?;
+
+    tracing::info!(
+        "gitpod service starting (HTTP:{} / SSH:{} / gRPC:{}:{})",
+        http_port,
+        ssh_port,
+        rpc_addr,
+        rpc_port
+    );
+
+    let http_task = tokio::spawn(git::http::run_http(
+        ctx.config.clone(),
+        ctx.db.clone(),
+        ctx.cache.clone(),
+        ctx.redis_pool.clone(),
+    ));
+
+    let ssh_task = tokio::spawn(git::ssh::run_ssh(
+        ctx.config.clone(),
+        ctx.db.clone(),
+        ctx.cache.clone(),
+        ctx.redis_pool.clone(),
+    ));
+
+    let rpc_addr_parsed =
+        format!("{}:{}", rpc_addr, rpc_port).parse::<std::net::SocketAddr>()?;
+    let sync_service =
+        git::sync::ReceiveSyncService::new(ctx.redis_pool.clone());
+    let git_server = git::rpc::server::GitServer::new(
+        rpc_addr_parsed,
+        ctx.db.clone(),
+        ctx.cache.clone(),
+        sync_service,
+    );
+    let rpc_task = tokio::spawn(async move {
+        git_server
+            .serve()
+            .await
+            .map_err(|e| anyhow::anyhow!("{}", e))
+    });
+
+    tokio::select! {
+        result = http_task => {
+            match result {
+                Ok(Ok(())) => tracing::info!("HTTP server stopped"),
+                Ok(Err(e)) => tracing::error!("HTTP server error: {}", e),
+                Err(e) => tracing::error!("HTTP task panicked: {}", e),
+            }
+        }
+        result = ssh_task => {
+            match result {
+                Ok(Ok(())) => tracing::info!("SSH server stopped"),
+                Ok(Err(e)) => tracing::error!("SSH server error: {}", e),
+                Err(e) => tracing::error!("SSH task panicked: {}", e),
+            }
+        }
+        result = rpc_task => {
+            match result {
+                Ok(Ok(())) => tracing::info!("gRPC server stopped"),
+                Ok(Err(e)) => tracing::error!("gRPC server error: {}", e),
+                Err(e) => tracing::error!("gRPC task panicked: {}", e),
+            }
+        }
+        _ = shutdown::wait_for_shutdown_signal() => {
+            tracing::info!("shutdown signal received, stopping gitpod service");
+        }
+    }
+
+    Ok(())
+}
diff --git a/app/gitpod/src/shutdown.rs b/app/gitpod/src/shutdown.rs
new file mode 100644
index 0000000..fe10327
--- /dev/null
+++ b/app/gitpod/src/shutdown.rs
@@ -0,0 +1,25 @@
+pub async fn wait_for_shutdown_signal() {
+    let ctrl_c = async {
+        tokio::signal::ctrl_c()
+            .await
+            .expect("failed to listen for ctrl_c event");
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        tokio::signal::unix::signal(
+            tokio::signal::unix::SignalKind::terminate(),
+        )
+        .expect("failed to listen for SIGTERM")
+        .recv()
+        .await;
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        _ = ctrl_c => {},
+        _ = terminate => {},
+    }
+}
diff --git a/app/gitsync/Cargo.toml b/app/gitsync/Cargo.toml
new file mode 100644
index 0000000..9228100
--- /dev/null
+++ b/app/gitsync/Cargo.toml
@@ -0,0 +1,36 @@
+[package]
+name = "app-gitsync"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[[bin]]
+name = "gitsync"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = { workspace = true }
+config = { workspace = true }
+cache = { workspace = true }
+db = { workspace = true }
+git = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter", "json"] }
+actix-web = { workspace = true }
+deadpool-redis = { workspace = true }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp"] }
+uuid = { workspace = true }
+serde_json = { workspace = true }
+sqlx = { workspace = true, features = ["postgres", "runtime-tokio"] }
+
+[lints]
+workspace = true
\ No newline at end of file
diff --git a/app/gitsync/src/context.rs b/app/gitsync/src/context.rs
new file mode 100644
index 0000000..45b5a8e
--- /dev/null
+++ b/app/gitsync/src/context.rs
@@ -0,0 +1,65 @@
+use std::time::Duration;
+
+use cache::{AppCache, AppCacheConfig};
+use config::AppConfig;
+use db::database::AppDatabase;
+use deadpool_redis::{PoolConfig, Runtime, Timeouts, cluster::Config};
+
+pub struct AppContext {
+    pub config: AppConfig,
+    pub db: AppDatabase,
+    pub cache: AppCache,
+    pub redis_pool: deadpool_redis::cluster::Pool,
+}
+
+impl AppContext {
+    pub async fn init() -> anyhow::Result<Self> {
+        let config = AppConfig::load();
+        init_tracing(&config)?;
+
+        tracing::info!("initializing database");
+        let db = AppDatabase::init(&config).await?;
+
+        tracing::info!("initializing cache");
+        let cache_config = AppCacheConfig::try_from(&config)?;
+        let cache = AppCache::init(cache_config).await?;
+
+        tracing::info!("initializing redis pool");
+        let redis_urls = config.redis_urls()?;
+        let pool_size = config.redis_pool_size()?;
+        let connect_timeout = config.redis_connect_timeout()?;
+        let acquire_timeout = config.redis_acquire_timeout()?;
+
+        let mut pool_config = PoolConfig::new(pool_size as usize);
+        pool_config.timeouts = Timeouts {
+            wait: Some(Duration::from_secs(acquire_timeout)),
+            create: Some(Duration::from_secs(connect_timeout)),
+            recycle: Some(Duration::from_secs(connect_timeout)),
+        };
+
+        let cfg = Config {
+            urls: Some(redis_urls),
+            connections: None,
+            pool: Some(pool_config),
+            read_from_replicas: false,
+        };
+        let redis_pool = cfg.create_pool(Some(Runtime::Tokio1))?;
+
+        Ok(Self {
+            config,
+            db,
+            cache,
+            redis_pool,
+        })
+    }
+}
+
+fn init_tracing(config: &AppConfig) -> anyhow::Result<()> {
+    let level = config.log_level()?;
+    let filter = tracing_subscriber::EnvFilter::try_new(&level)?;
+    tracing_subscriber::fmt()
+        .with_env_filter(filter)
+        .with_target(false)
+        .init();
+    Ok(())
+}
diff --git a/app/gitsync/src/health.rs b/app/gitsync/src/health.rs
new file mode 100644
index 0000000..e4a7e18
--- /dev/null
+++ b/app/gitsync/src/health.rs
@@ -0,0 +1,99 @@
+use std::time::Instant;
+
+use actix_web::dev::Service;
+use actix_web::{App, HttpResponse, HttpServer, dev::Server, web};
+use cache::AppCache;
+use db::database::AppDatabase;
+
+const REQUEST_LOG_EXCLUDED_PATHS: &[&str] = &[
+    "/health",
+    "/live",
+    "/ready",
+    "/metrics",
+    "/favicon.ico",
+    "/robots.txt",
+];
+
+fn should_log_request(path: &str) -> bool {
+    !REQUEST_LOG_EXCLUDED_PATHS.contains(&path)
+}
+
+async fn health(
+    db: web::Data<AppDatabase>,
+    cache: web::Data<AppCache>,
+) -> HttpResponse {
+    let db_ok = sqlx::query("SELECT 1").execute(db.reader()).await.is_ok();
+    let cache_ok = cache.ping_cluster().await.is_ok();
+
+    if db_ok && cache_ok {
+        HttpResponse::Ok().json(serde_json::json!({
+            "status": "ok",
+            "db": "ok",
+            "cache": "ok",
+        }))
+    } else {
+        HttpResponse::ServiceUnavailable().json(serde_json::json!({
+            "status": "unhealthy",
+            "db": if db_ok { "ok" } else { "error" },
+            "cache": if cache_ok { "ok" } else { "error" },
+        }))
+    }
+}
+
+pub fn start_health(
+    port: u16,
+    db: AppDatabase,
+    cache: AppCache,
+) -> anyhow::Result<Server> {
+    tracing::info!("health endpoint starting on 0.0.0.0:{}", port);
+
+    let srv = HttpServer::new(move || {
+        App::new()
+            .app_data(web::Data::new(db.clone()))
+            .app_data(web::Data::new(cache.clone()))
+            .wrap_fn(|req, srv| {
+                let should_log = should_log_request(req.path());
+                let method = req.method().clone();
+                let path = req.path().to_owned();
+                let peer_addr =
+                    req.connection_info().peer_addr().map(str::to_owned);
+                let started_at = Instant::now();
+                let fut = srv.call(req);
+
+                async move {
+                    match fut.await {
+                        Ok(res) => {
+                            if should_log {
+                                tracing::info!(
+                                    method = %method,
+                                    path = %path,
+                                    status = res.status().as_u16(),
+                                    elapsed_ms = started_at.elapsed().as_millis(),
+                                    peer_addr = peer_addr.as_deref().unwrap_or("-"),
+                                    "http request"
+                                );
+                            }
+                            Ok(res)
+                        }
+                        Err(err) => {
+                            if should_log {
+                                tracing::warn!(
+                                    method = %method,
+                                    path = %path,
+                                    elapsed_ms = started_at.elapsed().as_millis(),
+                                    peer_addr = peer_addr.as_deref().unwrap_or("-"),
+                                    error = %err,
+                                    "http request failed"
+                                );
+                            }
+                            Err(err)
+                        }
+                    }
+                }
+            })
+            .route("/health", web::get().to(health))
+    })
+    .bind(format!("0.0.0.0:{}", port))?;
+
+    Ok(srv.run())
+}
diff --git a/app/gitsync/src/main.rs b/app/gitsync/src/main.rs
new file mode 100644
index 0000000..55bd35a
--- /dev/null
+++ b/app/gitsync/src/main.rs
@@ -0,0 +1,51 @@
+mod context;
+mod health;
+mod shutdown;
+
+use context::AppContext;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let ctx = AppContext::init().await?;
+
+    tracing::info!("gitsync service starting");
+
+    let health_port = ctx.config.gitsync_health_port();
+    let health_server =
+        health::start_health(health_port, ctx.db.clone(), ctx.cache.clone())?;
+    let health_handle = health_server.handle();
+    let health_task = tokio::spawn(health_server);
+
+    let sync_service =
+        git::sync::ReceiveSyncService::new(ctx.redis_pool.clone());
+    let consumer = git::sync::consumer::SyncConsumer::new(sync_service, 5);
+    let worker = git::sync::worker::SyncWorker::new(
+        consumer,
+        ctx.db.clone(),
+        ctx.cache.clone(),
+        ctx.redis_pool.clone(),
+        ctx.config.clone(),
+        format!("gitsync-{}", uuid::Uuid::new_v4()),
+    );
+
+    let worker_task = tokio::spawn(async move { worker.run().await });
+
+    tokio::select! {
+        result = health_task => {
+            match result {
+                Ok(Ok(())) => tracing::info!("health server stopped"),
+                Ok(Err(e)) => tracing::error!("health server error: {}", e),
+                Err(e) => tracing::error!("health task panicked: {}", e),
+            }
+        }
+        _ = worker_task => {
+            tracing::info!("sync worker stopped");
+        }
+        _ = shutdown::wait_for_shutdown_signal() => {
+            tracing::info!("shutdown signal received, stopping gitsync service");
+            health_handle.stop(true).await;
+        }
+    }
+
+    Ok(())
+}
diff --git a/app/gitsync/src/shutdown.rs b/app/gitsync/src/shutdown.rs
new file mode 100644
index 0000000..fe10327
--- /dev/null
+++ b/app/gitsync/src/shutdown.rs
@@ -0,0 +1,25 @@
+pub async fn wait_for_shutdown_signal() {
+    let ctrl_c = async {
+        tokio::signal::ctrl_c()
+            .await
+            .expect("failed to listen for ctrl_c event");
+    };
+
+    #[cfg(unix)]
+    let terminate = async {
+        tokio::signal::unix::signal(
+            tokio::signal::unix::SignalKind::terminate(),
+        )
+        .expect("failed to listen for SIGTERM")
+        .recv()
+        .await;
+    };
+
+    #[cfg(not(unix))]
+    let terminate = std::future::pending::<()>();
+
+    tokio::select! {
+        _ = ctrl_c => {},
+        _ = terminate => {},
+    }
+}
diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 0000000..b23bf89
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,137 @@
+# GitDataAI Docker 配置
+
+## 文件说明
+
+### Dockerfile 文件
+
+| 文件名 | 服务 | 说明 |
+|--------|------|------|
+| `gitdata.Dockerfile` | GitData API | 主 API 服务 |
+| `email.Dockerfile` | Email Service | 邮件发送服务 |
+| `gitpod.Dockerfile` | GitPod Service | Git 服务 |
+| `gitsync.Dockerfile` | GitSync Service | Git 同步服务 |
+| `migrate.Dockerfile` | Database Migration | 数据库迁移工具 |
+| `web.Dockerfile` | Web Frontend | React 前端应用 |
+
+### 配置文件
+
+| 文件名 | 说明 |
+|--------|------|
+| `docker-compose.yml` | 完整的开发环境配置 |
+| `nginx.conf` | Nginx 反向代理配置 |
+
+## 快速开始
+
+### 1. 启动完整开发环境
+
+```bash
+# 进入 docker 目录
+cd docker
+
+# 启动所有服务
+docker-compose up -d
+
+# 查看服务状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f
+```
+
+### 2. 单独构建服务
+
+```bash
+# 构建 GitData API
+docker build -f docker/gitdata.Dockerfile -t gitdata-api .
+
+# 构建前端
+docker build -f docker/web.Dockerfile -t gitdata-web .
+```
+
+### 3. 环境变量配置
+
+创建 `.env` 文件配置环境变量：
+
+```bash
+# 数据库配置
+POSTGRES_USER=gitdata
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=app
+
+# MinIO 配置
+MINIO_ROOT_USER=admin
+MINIO_ROOT_PASSWORD=your_secure_password
+```
+
+## 服务端口
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| Web Frontend | 80 | 前端访问入口 |
+| GitData API | 8080 | 主 API 服务 |
+| Git HTTP | 5023 | Git HTTP 访问 |
+| Git RPC | 5030 | Git RPC 服务 |
+| SSH | 5022 | SSH Git 访问 |
+| GitPod | 5082 | GitPod 服务 |
+| GitSync | 5083 | GitSync 健康检查 |
+| PostgreSQL | 5432 | 数据库 |
+| Redis | 6379 | 缓存 |
+| Qdrant | 6333 | 向量数据库 |
+| NATS | 4222 | 消息队列 |
+| MinIO | 9000/9001 | 对象存储 |
+
+## 生产环境部署
+
+### 1. 修改环境变量
+
+```bash
+# 复制示例配置
+cp .env.example .env
+
+# 编辑配置文件，修改密码等敏感信息
+vim .env
+```
+
+### 2. 启动服务
+
+```bash
+# 使用生产配置启动
+docker-compose -f docker-compose.yml up -d
+
+# 查看服务状态
+docker-compose ps
+```
+
+### 3. 数据备份
+
+```bash
+# 备份 PostgreSQL
+docker exec gitdata-postgres pg_dump -U gitdata app > backup.sql
+
+# 备份 MinIO 数据
+docker cp gitdata-minio:/data ./minio-backup
+```
+
+## 常见问题
+
+### 1. 服务启动失败
+
+检查日志：
+```bash
+docker-compose logs <service-name>
+```
+
+### 2. 数据库连接失败
+
+确保 PostgreSQL 健康检查通过：
+```bash
+docker-compose ps postgres
+```
+
+### 3. 端口冲突
+
+修改 `docker-compose.yml` 中的端口映射：
+```yaml
+ports:
+  - "8081:8080"  # 修改宿主机端口
+```
\ No newline at end of file
diff --git a/docker/build.sh b/docker/build.sh
new file mode 100755
index 0000000..d0ccdb8
--- /dev/null
+++ b/docker/build.sh
@@ -0,0 +1,131 @@
+#!/bin/bash
+# GitDataAI Docker Build Script
+
+set -e
+
+# Get version from Cargo.toml
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CARGO_VERSION=$(grep -m1 'version' "${PROJECT_ROOT}/Cargo.toml" | sed 's/.*"\(.*\)".*/\1/')
+
+# Configuration
+REGISTRY=${REGISTRY:-""}
+TAG=${TAG:-"${CARGO_VERSION:-latest}"}
+PLATFORM=${PLATFORM:-"linux/amd64"}
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Services to build
+SERVICES=("gitdata" "email" "gitpod" "gitsync" "migrate" "web")
+
+# Function to print colored output
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Function to build a service
+build_service() {
+    local service=$1
+    local dockerfile="${PROJECT_ROOT}/docker/${service}.Dockerfile"
+    local image_name="gitdata-${service}"
+
+    # Add registry prefix if set
+    if [ -n "$REGISTRY" ]; then
+        image_name="${REGISTRY}/${image_name}"
+    fi
+
+    log_info "Building ${service}..."
+
+    if [ ! -f "$dockerfile" ]; then
+        log_error "Dockerfile not found: ${dockerfile}"
+        return 1
+    fi
+
+    docker build \
+        -f "$dockerfile" \
+        -t "${image_name}:${TAG}" \
+        --platform "$PLATFORM" \
+        "$PROJECT_ROOT"
+
+    log_info "Successfully built ${image_name}:${TAG}"
+}
+
+# Parse command line arguments
+BUILD_SERVICES=()
+BUILD_ALL=true
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --tag|-t)
+            TAG="$2"
+            shift 2
+            ;;
+        --registry|-r)
+            REGISTRY="$2"
+            shift 2
+            ;;
+        --platform|-p)
+            PLATFORM="$2"
+            shift 2
+            ;;
+        --help|-h)
+            echo "Usage: $0 [OPTIONS] [SERVICE...]"
+            echo ""
+            echo "Options:"
+            echo "  -t, --tag TAG        Docker image tag (default: latest)"
+            echo "  -r, --registry REG   Docker registry prefix"
+            echo "  -p, --platform PLAT  Target platform (default: linux/amd64)"
+            echo "  -h, --help           Show this help message"
+            echo ""
+            echo "Services:"
+            echo "  gitdata              Main API service"
+            echo "  email                Email service"
+            echo "  gitpod               GitPod service"
+            echo "  gitsync              GitSync service"
+            echo "  migrate              Database migration"
+            echo "  web                  Web frontend"
+            echo ""
+            echo "Examples:"
+            echo "  $0                              # Build all services"
+            echo "  $0 gitdata web                  # Build specific services"
+            echo "  $0 -t v1.0.0 -r registry.com   # Build with custom tag and registry"
+            exit 0
+            ;;
+        *)
+            BUILD_SERVICES+=("$1")
+            BUILD_ALL=false
+            shift
+            ;;
+    esac
+done
+
+# Build services
+log_info "Starting Docker build..."
+log_info "Registry: ${REGISTRY:-none}"
+log_info "Tag: ${TAG}"
+log_info "Platform: ${PLATFORM}"
+
+if [ "$BUILD_ALL" = true ]; then
+    log_info "Building all services..."
+    for service in "${SERVICES[@]}"; do
+        build_service "$service"
+    done
+else
+    log_info "Building specified services: ${BUILD_SERVICES[*]}"
+    for service in "${BUILD_SERVICES[@]}"; do
+        build_service "$service"
+    done
+fi
+
+log_info "Build completed successfully!"
\ No newline at end of file
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
new file mode 100644
index 0000000..447cd34
--- /dev/null
+++ b/docker/docker-compose.yml
@@ -0,0 +1,203 @@
+# GitDataAI Docker Compose
+# Full stack deployment configuration
+
+services:
+  # PostgreSQL Database
+  postgres:
+    image: postgres:16-alpine
+    container_name: gitdata-postgres
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-gitdata}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-gitdata123}
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-gitdata}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  # Redis Cluster
+  redis:
+    image: redis:7-alpine
+    container_name: gitdata-redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  # Qdrant Vector Database
+  qdrant:
+    image: qdrant/qdrant:latest
+    container_name: gitdata-qdrant
+    ports:
+      - "6333:6333"
+    volumes:
+      - qdrant_data:/qdrant/storage
+    restart: unless-stopped
+
+  # NATS Message Queue
+  nats:
+    image: nats:alpine
+    container_name: gitdata-nats
+    ports:
+      - "4222:4222"
+      - "8222:8222"
+    command: "--jetstream"
+    restart: unless-stopped
+
+  # MinIO S3 Storage
+  minio:
+    image: minio/minio:latest
+    container_name: gitdata-minio
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-admin}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-mysecret123}
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    volumes:
+      - minio_data:/data
+    restart: unless-stopped
+
+  # Database Migration
+  migrate:
+    build:
+      context: ..
+      dockerfile: docker/migrate.Dockerfile
+    container_name: gitdata-migrate
+    environment:
+      DATABASE_URL: postgres://${POSTGRES_USER:-gitdata}:${POSTGRES_PASSWORD:-gitdata123}@postgres:5432/${POSTGRES_DB:-app}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+  # GitData Main API Service
+  gitdata:
+    build:
+      context: ..
+      dockerfile: docker/gitdata.Dockerfile
+    container_name: gitdata-api
+    environment:
+      APP_DATABASE_URL: postgres://${POSTGRES_USER:-gitdata}:${POSTGRES_PASSWORD:-gitdata123}@postgres:5432/${POSTGRES_DB:-app}
+      APP_REDIS_URLS: redis://redis:6379
+      APP_QDRANT_URL: http://qdrant:6333/
+      NATS_URL: nats://nats:4222
+      APP_STORAGE_S3_ENDPOINT_URL: http://minio:9000
+      APP_STORAGE_S3_ACCESS_KEY_ID: ${MINIO_ROOT_USER:-admin}
+      APP_STORAGE_S3_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD:-mysecret123}
+    ports:
+      - "8080:8080"
+      - "5023:5023"
+      - "5030:5030"
+      - "5022:5022"
+    volumes:
+      - gitdata_repos:/app/data/repos
+      - gitdata_files:/app/data/files
+      - gitdata_avatar:/app/data/avatar
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      qdrant:
+        condition: service_started
+      nats:
+        condition: service_started
+      minio:
+        condition: service_started
+      migrate:
+        condition: service_completed_successfully
+    restart: unless-stopped
+
+  # Email Service
+  email:
+    build:
+      context: ..
+      dockerfile: docker/email.Dockerfile
+    container_name: gitdata-email
+    environment:
+      APP_DATABASE_URL: postgres://${POSTGRES_USER:-gitdata}:${POSTGRES_PASSWORD:-gitdata123}@postgres:5432/${POSTGRES_DB:-app}
+      APP_REDIS_URLS: redis://redis:6379
+      NATS_URL: nats://nats:4222
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      nats:
+        condition: service_started
+    restart: unless-stopped
+
+  # GitPod Service
+  gitpod:
+    build:
+      context: ..
+      dockerfile: docker/gitpod.Dockerfile
+    container_name: gitdata-gitpod
+    environment:
+      APP_DATABASE_URL: postgres://${POSTGRES_USER:-gitdata}:${POSTGRES_PASSWORD:-gitdata123}@postgres:5432/${POSTGRES_DB:-app}
+      APP_REDIS_URLS: redis://redis:6379
+    ports:
+      - "5082:5082"
+    volumes:
+      - gitdata_repos:/app/data/repos
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  # GitSync Service
+  gitsync:
+    build:
+      context: ..
+      dockerfile: docker/gitsync.Dockerfile
+    container_name: gitdata-gitsync
+    environment:
+      APP_DATABASE_URL: postgres://${POSTGRES_USER:-gitdata}:${POSTGRES_PASSWORD:-gitdata123}@postgres:5432/${POSTGRES_DB:-app}
+      APP_REDIS_URLS: redis://redis:6379
+    ports:
+      - "5083:5083"
+    volumes:
+      - gitdata_repos:/app/data/repos
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  # Web Frontend
+  web:
+    build:
+      context: ..
+      dockerfile: docker/web.Dockerfile
+    container_name: gitdata-web
+    ports:
+      - "80:80"
+    depends_on:
+      - gitdata
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+  redis_data:
+  qdrant_data:
+  minio_data:
+  gitdata_repos:
+  gitdata_files:
+  gitdata_avatar:
\ No newline at end of file
diff --git a/docker/gitdata.Dockerfile b/docker/gitdata.Dockerfile
new file mode 100644
index 0000000..6ada483
--- /dev/null
+++ b/docker/gitdata.Dockerfile
@@ -0,0 +1,74 @@
+# GitDataAI Backend - GitData Service
+# Multi-stage build for Rust application
+
+# Stage 1: Build the application
+FROM rust:1.96-bookworm AS builder
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    pkg-config \
+    libssl-dev \
+    libpq-dev \
+    cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy workspace files
+COPY Cargo.toml Cargo.lock ./
+COPY app/ app/
+COPY lib/ lib/
+
+# Build the application in release mode
+RUN cargo build --release --bin gitdata
+
+# Stage 2: Create runtime image
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    libssl3 \
+    libpq5 \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd -r -s /bin/false appuser
+
+# Create directories
+RUN mkdir -p /app/data/repos \
+    /app/data/files \
+    /app/data/avatar \
+    /app/logs \
+    && chown -R appuser:appuser /app
+
+# Copy binary from builder
+COPY --from=builder /app/target/release/gitdata /app/gitdata
+
+# Set ownership
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Set working directory
+WORKDIR /app
+
+# Expose ports
+# API port
+EXPOSE 8080
+# Git HTTP port
+EXPOSE 5023
+# Git RPC port
+EXPOSE 5030
+# SSH port
+EXPOSE 5022
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8080/health || exit 1
+
+# Run the application
+CMD ["./gitdata"]
\ No newline at end of file
diff --git a/docker/gitpod.Dockerfile b/docker/gitpod.Dockerfile
new file mode 100644
index 0000000..deca8dc
--- /dev/null
+++ b/docker/gitpod.Dockerfile
@@ -0,0 +1,65 @@
+# GitDataAI Backend - GitPod Service
+# Multi-stage build for Rust application
+
+# Stage 1: Build the application
+FROM rust:1.96-bookworm AS builder
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    pkg-config \
+    libssl-dev \
+    libpq-dev \
+    cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy workspace files
+COPY Cargo.toml Cargo.lock ./
+COPY app/ app/
+COPY lib/ lib/
+
+# Build the application in release mode
+RUN cargo build --release --bin gitpod
+
+# Stage 2: Create runtime image
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    libssl3 \
+    libpq5 \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd -r -s /bin/false appuser
+
+# Create directories
+RUN mkdir -p /app/data/repos \
+    /app/logs \
+    && chown -R appuser:appuser /app
+
+# Copy binary from builder
+COPY --from=builder /app/target/release/gitpod /app/gitpod
+
+# Set ownership
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Set working directory
+WORKDIR /app
+
+# Expose port
+EXPOSE 5082
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:5082/health || exit 1
+
+# Run the application
+CMD ["./gitpod"]
\ No newline at end of file
diff --git a/docker/gitsync.Dockerfile b/docker/gitsync.Dockerfile
new file mode 100644
index 0000000..6ce8777
--- /dev/null
+++ b/docker/gitsync.Dockerfile
@@ -0,0 +1,65 @@
+# GitDataAI Backend - GitSync Service
+# Multi-stage build for Rust application
+
+# Stage 1: Build the application
+FROM rust:1.96-bookworm AS builder
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    pkg-config \
+    libssl-dev \
+    libpq-dev \
+    cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy workspace files
+COPY Cargo.toml Cargo.lock ./
+COPY app/ app/
+COPY lib/ lib/
+
+# Build the application in release mode
+RUN cargo build --release --bin gitsync
+
+# Stage 2: Create runtime image
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    libssl3 \
+    libpq5 \
+    ca-certificates \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd -r -s /bin/false appuser
+
+# Create directories
+RUN mkdir -p /app/data/repos \
+    /app/logs \
+    && chown -R appuser:appuser /app
+
+# Copy binary from builder
+COPY --from=builder /app/target/release/gitsync /app/gitsync
+
+# Set ownership
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Set working directory
+WORKDIR /app
+
+# Expose health check port
+EXPOSE 5083
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:5083/health || exit 1
+
+# Run the application
+CMD ["./gitsync"]
\ No newline at end of file
diff --git a/docker/migrate.Dockerfile b/docker/migrate.Dockerfile
new file mode 100644
index 0000000..dab22a0
--- /dev/null
+++ b/docker/migrate.Dockerfile
@@ -0,0 +1,58 @@
+# GitDataAI Database Migration Dockerfile
+# Multi-stage build for Rust migration tool
+
+# Stage 1: Build the application
+FROM rust:1.96-bookworm AS builder
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    pkg-config \
+    libssl-dev \
+    libpq-dev \
+    cmake \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy workspace files
+COPY Cargo.toml Cargo.lock ./
+COPY app/ app/
+COPY lib/ lib/
+
+# Build the migration binary
+RUN cargo build --release --bin migrate
+
+# Stage 2: Create runtime image
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    libssl3 \
+    libpq5 \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd -r -s /bin/false appuser
+
+# Create app directory
+RUN mkdir -p /app && chown -R appuser:appuser /app
+
+# Copy binary from builder
+COPY --from=builder /app/target/release/migrate /app/migrate
+
+# Copy migration files
+COPY --from=builder /app/lib/migrate/sql /app/sql
+
+# Set ownership
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Set working directory
+WORKDIR /app
+
+# Run migrations by default
+CMD ["./migrate", "up"]
\ No newline at end of file
diff --git a/docker/nginx.conf b/docker/nginx.conf
new file mode 100644
index 0000000..8455432
--- /dev/null
+++ b/docker/nginx.conf
@@ -0,0 +1,75 @@
+server {
+    listen 80;
+    server_name localhost;
+    
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types
+        text/plain
+        text/css
+        text/xml
+        text/javascript
+        application/json
+        application/javascript
+        application/xml
+        application/rss+xml
+        image/svg+xml;
+
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    # Root directory
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Enable static asset caching
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        try_files $uri =404;
+    }
+
+    # API proxy (if needed)
+    location /api/ {
+        proxy_pass http://gitdata:8080/api/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # Socket.IO proxy
+    location /socket.io/ {
+        proxy_pass http://gitdata:8080/socket.io/;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # SPA fallback
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Health check endpoint
+    location /health {
+        access_log off;
+        return 200 'OK';
+        add_header Content-Type text/plain;
+    }
+}
\ No newline at end of file
diff --git a/docker/push.sh b/docker/push.sh
new file mode 100755
index 0000000..7804c5b
--- /dev/null
+++ b/docker/push.sh
@@ -0,0 +1,128 @@
+#!/bin/bash
+# GitDataAI Docker Push Script
+
+set -e
+
+# Get version from Cargo.toml
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CARGO_VERSION=$(grep -m1 'version' "${PROJECT_ROOT}/Cargo.toml" | sed 's/.*"\(.*\)".*/\1/')
+
+# Configuration
+REGISTRY=${REGISTRY:-""}
+TAG=${TAG:-"${CARGO_VERSION:-latest}"}
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Services to push
+SERVICES=("gitdata" "email" "gitpod" "gitsync" "migrate" "web")
+
+# Function to print colored output
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Function to push a service
+push_service() {
+    local service=$1
+    local image_name="gitdata-${service}"
+
+    # Add registry prefix if set
+    if [ -n "$REGISTRY" ]; then
+        image_name="${REGISTRY}/${image_name}"
+    fi
+
+    log_info "Pushing ${service}..."
+
+    # Check if image exists locally
+    if ! docker image inspect "${image_name}:${TAG}" > /dev/null 2>&1; then
+        log_error "Image not found: ${image_name}:${TAG}"
+        log_error "Please build the image first with: ./build.sh ${service}"
+        return 1
+    fi
+
+    docker push "${image_name}:${TAG}"
+
+    log_info "Successfully pushed ${image_name}:${TAG}"
+}
+
+# Parse command line arguments
+PUSH_SERVICES=()
+PUSH_ALL=true
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --tag|-t)
+            TAG="$2"
+            shift 2
+            ;;
+        --registry|-r)
+            REGISTRY="$2"
+            shift 2
+            ;;
+        --help|-h)
+            echo "Usage: $0 [OPTIONS] [SERVICE...]"
+            echo ""
+            echo "Options:"
+            echo "  -t, --tag TAG        Docker image tag (default: latest)"
+            echo "  -r, --registry REG   Docker registry prefix (required)"
+            echo "  -h, --help           Show this help message"
+            echo ""
+            echo "Services:"
+            echo "  gitdata              Main API service"
+            echo "  email                Email service"
+            echo "  gitpod               GitPod service"
+            echo "  gitsync              GitSync service"
+            echo "  migrate              Database migration"
+            echo "  web                  Web frontend"
+            echo ""
+            echo "Examples:"
+            echo "  $0 -r registry.com                    # Push all services"
+            echo "  $0 -r registry.com gitdata web        # Push specific services"
+            echo "  $0 -r registry.com -t v1.0.0          # Push with custom tag"
+            exit 0
+            ;;
+        *)
+            PUSH_SERVICES+=("$1")
+            PUSH_ALL=false
+            shift
+            ;;
+    esac
+done
+
+# Validate registry
+if [ -z "$REGISTRY" ]; then
+    log_error "Registry is required. Use -r or --registry to specify."
+    echo "Example: $0 -r registry.com"
+    exit 1
+fi
+
+# Push services
+log_info "Starting Docker push..."
+log_info "Registry: ${REGISTRY}"
+log_info "Tag: ${TAG}"
+
+if [ "$PUSH_ALL" = true ]; then
+    log_info "Pushing all services..."
+    for service in "${SERVICES[@]}"; do
+        push_service "$service"
+    done
+else
+    log_info "Pushing specified services: ${PUSH_SERVICES[*]}"
+    for service in "${PUSH_SERVICES[@]}"; do
+        push_service "$service"
+    done
+fi
+
+log_info "Push completed successfully!"
\ No newline at end of file
diff --git a/docker/web.Dockerfile b/docker/web.Dockerfile
new file mode 100644
index 0000000..a45e549
--- /dev/null
+++ b/docker/web.Dockerfile
@@ -0,0 +1,62 @@
+# GitDataAI Frontend Dockerfile
+# Multi-stage build for React application with Bun
+
+# Stage 1: Build the application
+FROM node:24-bookworm AS builder
+
+# Install bun
+RUN npm install -g bun
+
+# Create app directory
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lock ./
+
+# Install dependencies
+RUN bun install --frozen-lockfile
+
+# Copy source code
+COPY src/ src/
+COPY public/ public/
+COPY index.html ./
+COPY vite.config.ts ./
+COPY tsconfig*.json ./
+COPY eslint.config.js ./
+COPY components.json ./
+COPY orval.config.ts ./
+
+# Build the application
+RUN bun run build
+
+# Stage 2: Create runtime image with Nginx
+FROM nginx:alpine
+
+# Copy custom nginx configuration
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+
+# Copy built assets from builder
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+# Create non-root user
+RUN adduser -D -S -h /var/cache/nginx -s /sbin/nologin -G nginx appuser
+
+# Set ownership
+RUN chown -R appuser:nginx /var/cache/nginx \
+    && chown -R appuser:nginx /var/log/nginx \
+    && chown -R appuser:nginx /etc/nginx/conf.d \
+    && touch /var/run/nginx.pid \
+    && chown -R appuser:nginx /var/run/nginx.pid
+
+# Switch to non-root user
+USER appuser
+
+# Expose port
+EXPOSE 80
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1
+
+# Start Nginx
+CMD ["nginx", "-g", "daemon off;"]
\ No newline at end of file
diff --git a/lib/ai/Cargo.toml b/lib/ai/Cargo.toml
new file mode 100644
index 0000000..c58fbfb
--- /dev/null
+++ b/lib/ai/Cargo.toml
@@ -0,0 +1,37 @@
+[package]
+name = "ai"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "ai"
+[dependencies]
+rig-core = { workspace = true, features = ["derive"] }
+tokio = { workspace = true, features = ["full"] }
+tokio-util = { workspace = true }
+tokio-stream = { workspace = true }
+config = { workspace = true }
+cache = { workspace = true }
+db = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+serde_json = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+qdrant-client = { workspace = true, features = ["serde"] }
+async-trait = { workspace = true }
+redis = { workspace = true }
+uuid = { workspace = true, features = ["v4", "v5", "serde"] }
+reqwest = { workspace = true }
+futures = { workspace = true }
+[lints]
+workspace = true
diff --git a/lib/ai/agent/agent.rs b/lib/ai/agent/agent.rs
new file mode 100644
index 0000000..5902500
--- /dev/null
+++ b/lib/ai/agent/agent.rs
@@ -0,0 +1,543 @@
+use futures::StreamExt;
+use rig::agent::AgentBuilder;
+use rig::client::CompletionClient;
+use rig::streaming::StreamingPrompt;
+use rig::tool::ToolDyn;
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+use tracing::{info, warn};
+
+use super::config::AgentConfig;
+use super::helpers::{build_input_string, check_token_budget, estimate_tokens};
+use super::hooks::{HookChain, HookLlmResponse, HookMessage, HookToolDef, ToolCallOutcome, ToolGuardrailDecision};
+use super::persistence::ActiveAgentRun;
+use super::request::{AgentRequest, AgentResult, AgentStep, ToolCallRecord};
+use super::subagent::run_experts;
+use super::RigStreamChunk;
+use crate::client::AiClient;
+use crate::error::{AiError, AiResult};
+
+pub struct RigAgent {
+    pub client: AiClient,
+    pub config: AgentConfig,
+    pub hooks: HookChain,
+}
+
+impl RigAgent {
+    pub fn new(client: AiClient, config: AgentConfig) -> AiResult<Self> {
+        config.validate()?;
+        Ok(Self {
+            client,
+            config,
+            hooks: HookChain::empty(),
+        })
+    }
+
+    pub fn with_hooks(mut self, hooks: HookChain) -> Self {
+        self.hooks = hooks;
+        self
+    }
+
+    pub fn config(&self) -> &AgentConfig {
+        &self.config
+    }
+
+    pub async fn chat(
+        &self,
+        request: AgentRequest,
+        tools: Vec<Box<dyn ToolDyn>>,
+    ) -> AiResult<String> {
+        let (mut rx, handle) = self.run(request, tools);
+        tokio::spawn(async move {
+            while rx.recv().await.is_some() {}
+        });
+        let result = handle.await.map_err(|_| {
+            AiError::Response("agent task panicked".to_string())
+        })?;
+        result.map(|r| r.output)
+    }
+
+    #[allow(clippy::too_many_lines)]
+    pub fn run(
+        &self,
+        request: AgentRequest,
+        tools: Vec<Box<dyn ToolDyn>>,
+    ) -> (
+        tokio::sync::mpsc::Receiver<RigStreamChunk>,
+        tokio::task::JoinHandle<AiResult<AgentResult>>,
+    ) {
+        let (tx, rx) = mpsc::channel::<RigStreamChunk>(256);
+
+        let model_name = self.config.model.clone();
+        let max_iterations = self.config.max_iterations;
+        let client = self.client.llm_client().clone();
+        let ai_client = self.client.clone();
+        let agent_config = self.config.clone();
+        let system_prompt = self.config.system_prompt.clone();
+        let temperature = self.config.temperature;
+        let max_completion_tokens = self.config.max_completion_tokens;
+        let max_total_tokens = self.config.max_total_tokens_per_run;
+        let cancellation = request.cancellation_token.clone();
+        let timeout = request.timeout;
+        let hooks = self.hooks.clone();
+
+        let filtered_tools: Vec<Box<dyn ToolDyn>> = tools
+            .into_iter()
+            .filter(|tool| self.config.is_tool_exposed(&tool.name()))
+            .collect();
+
+        let handle = tokio::spawn(async move {
+            execute_agent_run(
+                client,
+                model_name,
+                system_prompt,
+                request,
+                filtered_tools,
+                max_iterations,
+                ai_client,
+                agent_config,
+                temperature,
+                max_completion_tokens,
+                max_total_tokens,
+                cancellation,
+                timeout,
+                hooks,
+                tx,
+            )
+            .await
+        });
+
+        (rx, handle)
+    }
+}
+
+#[allow(clippy::too_many_lines, clippy::too_many_arguments)]
+async fn execute_agent_run(
+    client: rig::providers::openai::Client,
+    model_name: String,
+    system_prompt: String,
+    request: AgentRequest,
+    tools: Vec<Box<dyn ToolDyn>>,
+    max_iterations: usize,
+    ai_client: AiClient,
+    agent_config: AgentConfig,
+    temperature: Option<f64>,
+    max_completion_tokens: Option<u64>,
+    max_total_tokens: Option<i64>,
+    cancellation: Option<CancellationToken>,
+    timeout: Option<std::time::Duration>,
+    hooks: HookChain,
+    tx: mpsc::Sender<RigStreamChunk>,
+) -> AiResult<AgentResult> {
+    if let Some(ref ctx) = request.run_context {
+        let _ = hooks.run_session_start(ctx).await;
+    }
+
+    let model = client.completion_model(&model_name);
+    let mut agent_builder = AgentBuilder::new(model)
+        .preamble(&system_prompt)
+        .tools(tools)
+        .default_max_turns(max_iterations);
+
+    if let Some(temp) = temperature {
+        agent_builder = agent_builder.temperature(temp);
+    }
+    if let Some(mt) = max_completion_tokens {
+        agent_builder = agent_builder.max_tokens(mt);
+    }
+
+    let agent = agent_builder.build();
+    let mut input = build_input_string(&request);
+
+    // ---- SubAgent execution ----
+    let expert_outputs = if !request.experts.is_empty() {
+        let run = ActiveAgentRun {
+            conversation_id: request.run_context.as_ref().and_then(|c| c.conversation_id),
+            message_id: None,
+            invocation_id: request.run_context.as_ref().and_then(|c| c.invocation_id),
+            session_id: request.run_context.as_ref().and_then(|c| c.session_id),
+            user_id: request.run_context.as_ref().and_then(|c| c.user_id),
+            started_at: std::time::Instant::now(),
+            current_step: 0,
+        };
+        let realtime = request.run_context.as_ref().and_then(|c| c.realtime.as_ref());
+
+        // Notify frontend that subagents are starting.
+        for expert in &request.experts {
+            let _ = tx
+                .send(RigStreamChunk::SubagentStarted {
+                    subagent_id: expert.id.clone(),
+                    role: expert.role.clone(),
+                    task: expert.task.clone(),
+                })
+                .await;
+        }
+
+        match run_experts(&ai_client, &agent_config, &request.experts, realtime, &run).await {
+            Ok(outputs) => {
+                for out in &outputs {
+                    let _ = tx
+                        .send(RigStreamChunk::SubagentCompleted {
+                            subagent_id: out.id.clone(),
+                            role: out.role.clone(),
+                            task: out.task.clone(),
+                            output: out.output.clone(),
+                        })
+                        .await;
+                    input.push_str(&format!(
+                        "\n--- Subagent: {} (role: {}) ---\nTask: {}\nResult: {}\n",
+                        out.id, out.role, out.task, out.output
+                    ));
+                }
+                outputs
+            }
+            Err(e) => {
+                warn!(error = %e, "subagent execution failed, continuing without expert inputs");
+                let _ = tx
+                    .send(RigStreamChunk::SubagentFailed {
+                        error: e.to_string(),
+                    })
+                    .await;
+                Vec::new()
+            }
+        }
+    } else {
+        Vec::new()
+    };
+
+    let estimated_input_tokens = estimate_tokens(&input);
+
+    if let Some(limit) = max_total_tokens
+        && estimated_input_tokens > limit as u64
+    {
+        return Err(AiError::TokenBudgetExceeded {
+            estimated: estimated_input_tokens,
+            limit,
+        });
+    }
+
+    if !hooks.is_empty() {
+        let hook_messages: Vec<HookMessage> = request
+            .messages
+            .iter()
+            .map(|m| HookMessage {
+                role: match m {
+                    super::request::AgentMessage::User(_) => "user".to_string(),
+                    super::request::AgentMessage::Assistant(_) => {
+                        "assistant".to_string()
+                    }
+                },
+                content: match m {
+                    super::request::AgentMessage::User(c) => Some(c.clone()),
+                    super::request::AgentMessage::Assistant(c) => {
+                        Some(c.clone())
+                    }
+                },
+                tool_calls: None,
+                tool_call_id: None,
+            })
+            .collect();
+        let hook_tools: Vec<HookToolDef> = Vec::new();
+        let _ = hooks.run_pre_llm_call(&hook_messages, &hook_tools).await;
+    }
+
+    let stream_future = agent
+        .stream_prompt(&input)
+        .with_history(Vec::<rig::completion::Message>::new())
+        .multi_turn(max_iterations);
+
+    let stream = if let Some(dur) = timeout {
+        match tokio::time::timeout(dur, stream_future).await {
+            Ok(stream) => stream,
+            Err(_elapsed) => {
+                let _ = tx
+                    .send(RigStreamChunk::Failed {
+                        error: format!("agent timed out after {}s", dur.as_secs()),
+                    })
+                    .await;
+                return Err(AiError::Timeout {
+                    seconds: dur.as_secs(),
+                });
+            }
+        }
+    } else {
+        stream_future.await
+    };
+
+    tokio::pin!(stream);
+
+    let mut steps = Vec::new();
+    let mut delta_index = 0usize;
+    let mut current_step_tool_calls: Vec<ToolCallRecord> = Vec::new();
+    let mut current_step_assistant = String::new();
+    let mut current_step_reasoning = String::new();
+    let mut accumulated_output_chars: usize = 0;
+
+    while let Some(item) = stream.next().await {
+        if cancellation.as_ref().is_some_and(|ct| ct.is_cancelled()) {
+            let _ = tx
+                .send(RigStreamChunk::Failed {
+                    error: "cancelled".to_string(),
+                })
+                .await;
+            return Err(AiError::Response("agent run cancelled".to_string()));
+        }
+
+        if let Some(limit) = max_total_tokens
+            && check_token_budget(estimated_input_tokens, accumulated_output_chars, limit)
+        {
+            let _ = tx
+                .send(RigStreamChunk::Failed {
+                    error: format!("token budget exceeded: limit {limit}"),
+                })
+                .await;
+            return Err(AiError::TokenBudgetExceeded {
+                estimated: estimated_input_tokens
+                    + (accumulated_output_chars as f64 / 2.5).ceil() as u64,
+                limit,
+            });
+        }
+
+        match item {
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::Text(text),
+            )) => {
+                accumulated_output_chars += text.text.chars().count();
+                current_step_assistant.push_str(&text.text);
+                let _ = tx
+                    .send(RigStreamChunk::TextDelta {
+                        index: delta_index,
+                        content: text.text.clone(),
+                    })
+                    .await;
+                delta_index += 1;
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::Reasoning(reasoning),
+            )) => {
+                for part in &reasoning.content {
+                    if let rig::completion::message::ReasoningContent::Text {
+                        text, ..
+                    } = part
+                    {
+                        accumulated_output_chars += text.chars().count();
+                        current_step_reasoning.push_str(text);
+                        let _ = tx
+                            .send(RigStreamChunk::Thinking {
+                                index: delta_index,
+                                content: text.clone(),
+                            })
+                            .await;
+                        delta_index += 1;
+                    }
+                }
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::ReasoningDelta {
+                    reasoning, ..
+                },
+            )) => {
+                accumulated_output_chars += reasoning.chars().count();
+                current_step_reasoning.push_str(&reasoning);
+                let _ = tx
+                    .send(RigStreamChunk::Thinking {
+                        index: delta_index,
+                        content: reasoning.clone(),
+                    })
+                    .await;
+                delta_index += 1;
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::ToolCall {
+                    tool_call,
+                    internal_call_id: _,
+                },
+            )) => {
+                let args = match &tool_call.function.arguments {
+                    serde_json::Value::String(s) => s.clone(),
+                    v => serde_json::to_string(v).unwrap_or_default(),
+                };
+                accumulated_output_chars += args.chars().count();
+
+                let tool_name = tool_call.function.name.clone();
+                let tool_args: serde_json::Value =
+                    serde_json::from_str(&args).unwrap_or_default();
+
+                if let Ok(Some(decision)) = hooks.run_pre_tool_call(&tool_name, &tool_args).await {
+                    match decision {
+                        ToolGuardrailDecision::Allow => {}
+                        ToolGuardrailDecision::Block { reason } => {
+                            let _ = tx
+                                .send(RigStreamChunk::ToolCallFinished {
+                                    tool_call_id: tool_call.id.clone(),
+                                    tool_name: tool_name.clone(),
+                                    output: format!("blocked: {reason}"),
+                                    error: Some(reason),
+                                })
+                                .await;
+                            current_step_tool_calls.push(ToolCallRecord {
+                                id: tool_call.id.clone(),
+                                name: tool_name.clone(),
+                                arguments: tool_args.clone(),
+                                output: None,
+                                error: Some("blocked by guardrail".to_string()),
+                                elapsed_ms: None,
+                            });
+                            continue;
+                        }
+                        ToolGuardrailDecision::RequireApproval { message } => {
+                            let _ = tx
+                                .send(RigStreamChunk::ToolCallFinished {
+                                    tool_call_id: tool_call.id.clone(),
+                                    tool_name: tool_name.clone(),
+                                    output: format!("awaiting approval: {message}"),
+                                    error: None,
+                                })
+                                .await;
+                            current_step_tool_calls.push(ToolCallRecord {
+                                id: tool_call.id.clone(),
+                                name: tool_name.clone(),
+                                arguments: tool_args.clone(),
+                                output: None,
+                                error: Some(format!("requires approval: {message}")),
+                                elapsed_ms: None,
+                            });
+                            continue;
+                        }
+                    }
+                }
+
+                let _ = tx
+                    .send(RigStreamChunk::ToolCallStarted {
+                        tool_call_id: tool_call.id.clone(),
+                        tool_name: tool_name.clone(),
+                        arguments: args.clone(),
+                    })
+                    .await;
+                current_step_tool_calls.push(ToolCallRecord {
+                    id: tool_call.id.clone(),
+                    name: tool_name.clone(),
+                    arguments: tool_args.clone(),
+                    output: None,
+                    error: None,
+                    elapsed_ms: None,
+                });
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamUserItem(
+                rig::streaming::StreamedUserContent::ToolResult { tool_result, .. },
+            )) => {
+                let content =
+                    super::helpers::tool_result_content_to_string(&tool_result.content);
+                accumulated_output_chars += content.chars().count();
+
+                if let Some(last) = current_step_tool_calls.last_mut()
+                    && last.id == tool_result.id
+                {
+                    last.output = Some(serde_json::from_str(&content).unwrap_or_default());
+                }
+
+                let tool_name = current_step_tool_calls
+                    .last()
+                    .map(|tc| tc.name.clone())
+                    .unwrap_or_default();
+
+                let _ = tx
+                    .send(RigStreamChunk::ToolCallFinished {
+                        tool_call_id: tool_result.id.clone(),
+                        tool_name,
+                        output: content.clone(),
+                        error: None,
+                    })
+                    .await;
+
+                if !hooks.is_empty() {
+                    let outcome = ToolCallOutcome {
+                        name: tool_result.id.clone(),
+                        arguments: serde_json::Value::Null,
+                        output: Some(serde_json::Value::String(content)),
+                        error: None,
+                        elapsed_ms: 0,
+                    };
+                    let _ = hooks.run_post_tool_call(&outcome).await;
+                }
+            }
+            Ok(rig::agent::MultiTurnStreamItem::FinalResponse(resp)) => {
+                let usage = resp.usage();
+
+                if !current_step_tool_calls.is_empty() || !current_step_assistant.is_empty() {
+                    let reasoning = (!current_step_reasoning.is_empty())
+                        .then_some(std::mem::take(&mut current_step_reasoning));
+                    steps.push(AgentStep {
+                        index: steps.len(),
+                        assistant: (!current_step_assistant.is_empty())
+                            .then_some(std::mem::take(&mut current_step_assistant)),
+                        reasoning_content: reasoning,
+                        tool_calls: std::mem::take(&mut current_step_tool_calls),
+                        reflection: None,
+                    });
+                }
+                let output = steps
+                    .last()
+                    .and_then(|s| s.assistant.clone())
+                    .unwrap_or_default();
+
+                if !hooks.is_empty() {
+                    let hook_response = HookLlmResponse {
+                        content: Some(output.clone()),
+                        tool_calls: None,
+                        input_tokens: usage.input_tokens,
+                        output_tokens: usage.output_tokens,
+                        finish_reason: None,
+                    };
+                    let _ = hooks.run_post_llm_call(&hook_response).await;
+                }
+
+                info!(
+                    steps = steps.len(),
+                    input_tokens = usage.input_tokens,
+                    output_tokens = usage.output_tokens,
+                    "agent run completed"
+                );
+
+                let _ = tx
+                    .send(RigStreamChunk::Final {
+                        content: output.clone(),
+                        input_tokens: usage.input_tokens,
+                        output_tokens: usage.output_tokens,
+                    })
+                    .await;
+
+                if let Some(ref ctx) = request.run_context {
+                    let _ = hooks.run_session_end(ctx, true).await;
+                }
+
+                return Ok(AgentResult {
+                    output,
+                    steps,
+                    expert_outputs,
+                    input_tokens: usage.input_tokens as i64,
+                    output_tokens: usage.output_tokens as i64,
+                });
+            }
+            Err(e) => {
+                let err = format!("{e}");
+                warn!(error = %err, "agent stream error");
+                let _ = tx.send(RigStreamChunk::Failed { error: err }).await;
+
+                if let Some(ref ctx) = request.run_context {
+                    let _ = hooks.run_session_end(ctx, false).await;
+                }
+                return Err(AiError::Api(format!("{e}")));
+            }
+            _ => {}
+        }
+    }
+
+    Err(AiError::Response("agent stream ended without final response".to_string()))
+}
+
+impl Clone for HookChain {
+    fn clone(&self) -> Self {
+        HookChain::empty()
+    }
+}
diff --git a/lib/ai/agent/compression.rs b/lib/ai/agent/compression.rs
new file mode 100644
index 0000000..331141c
--- /dev/null
+++ b/lib/ai/agent/compression.rs
@@ -0,0 +1,222 @@
+use crate::error::AiResult;
+
+/// Compression strategy controlling when and how context compaction occurs.
+#[derive(Clone, Debug)]
+pub struct CompressionStrategy {
+    /// Token threshold that triggers compaction.
+    pub threshold_tokens: i64,
+    /// Target token count after compaction.
+    pub target_tokens: i64,
+    /// Number of recent message pairs to always preserve.
+    pub preserve_last_n_pairs: usize,
+    /// Optional model override for the compaction LLM call.
+    pub summary_model: String,
+    /// Reserve this many tokens for the compaction prompt itself.
+    pub reserve_tokens: i64,
+    /// Whether to generate branch summaries when forking.
+    pub branch_summarization: bool,
+    /// Custom instructions appended to the compaction prompt.
+    pub custom_instructions: Option<String>,
+    /// Maximum word count for compaction summaries.
+    pub max_summary_words: usize,
+}
+
+impl Default for CompressionStrategy {
+    fn default() -> Self {
+        Self {
+            threshold_tokens: 64_000,
+            target_tokens: 32_000,
+            preserve_last_n_pairs: 4,
+            summary_model: String::new(),
+            reserve_tokens: 16_384,
+            branch_summarization: true,
+            custom_instructions: None,
+            max_summary_words: 1500,
+        }
+    }
+}
+
+impl CompressionStrategy {
+    pub fn new(threshold_tokens: i64, target_tokens: i64) -> Self {
+        Self {
+            threshold_tokens,
+            target_tokens,
+            ..Default::default()
+        }
+    }
+
+    pub fn with_preserve_last(mut self, n: usize) -> Self {
+        self.preserve_last_n_pairs = n;
+        self
+    }
+
+    pub fn with_summary_model(mut self, model: impl Into<String>) -> Self {
+        self.summary_model = model.into();
+        self
+    }
+
+    pub fn with_reserve_tokens(mut self, tokens: i64) -> Self {
+        self.reserve_tokens = tokens;
+        self
+    }
+
+    pub fn with_branch_summarization(mut self, enabled: bool) -> Self {
+        self.branch_summarization = enabled;
+        self
+    }
+
+    pub fn with_custom_instructions(mut self, instructions: impl Into<String>) -> Self {
+        self.custom_instructions = Some(instructions.into());
+        self
+    }
+
+    pub fn with_max_summary_words(mut self, words: usize) -> Self {
+        self.max_summary_words = words;
+        self
+    }
+
+    /// Check whether compaction should be triggered based on current token count.
+    pub fn should_compact(&self, current_tokens: i64) -> bool {
+        current_tokens >= self.threshold_tokens
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct CompactionResult {
+    pub summary: String,
+    pub messages_compacted: usize,
+    pub tokens_saved: i64,
+    /// Whether this was a branch summary (vs. standard compaction).
+    pub is_branch_summary: bool,
+}
+
+impl CompactionResult {
+    pub fn new(summary: String, messages_compacted: usize, tokens_saved: i64) -> Self {
+        Self {
+            summary,
+            messages_compacted,
+            tokens_saved,
+            is_branch_summary: false,
+        }
+    }
+
+    pub fn branch_summary(summary: String, entries_summarized: usize) -> Self {
+        Self {
+            summary,
+            messages_compacted: entries_summarized,
+            tokens_saved: 0,
+            is_branch_summary: true,
+        }
+    }
+}
+
+/// Build the compaction prompt for standard context compression.
+pub fn build_compression_prompt(
+    existing_summary: Option<&str>,
+    messages_text: &str,
+) -> String {
+    build_compression_prompt_with_options(existing_summary, messages_text, None, 1500)
+}
+
+/// Build the compaction prompt with custom instructions and word limit.
+pub fn build_compression_prompt_with_options(
+    existing_summary: Option<&str>,
+    messages_text: &str,
+    custom_instructions: Option<&str>,
+    max_words: usize,
+) -> String {
+    let custom = custom_instructions
+        .map(|ci| format!("\n\nAdditional instructions: {ci}"))
+        .unwrap_or_default();
+
+    if let Some(summary) = existing_summary {
+        format!(
+            "## Previous Summary\n{summary}\n\n## New Messages\n{messages_text}\n\n\
+             Combine the previous summary and the new messages into a concise, \
+             single-paragraph summary of the conversation. Preserve facts, \
+             decisions, code snippets, and anything essential for continuing \
+             work. Target up to {max_words} words.{custom} \
+             Output ONLY the summary text, no preamble.",
+        )
+    } else {
+        format!(
+            "## Conversation\n{messages_text}\n\n\
+             Summarise the conversation above into a concise, single-paragraph \
+             summary. Preserve facts, decisions, code snippets, and anything \
+             essential for continuing work. Target up to {max_words} words.{custom} \
+             Output ONLY the summary text, no preamble.",
+        )
+    }
+}
+
+/// Build a prompt for generating a branch summary.
+///
+/// Used when the user forks a conversation from a different point in the
+/// session tree. Summarizes the divergent branch so context is preserved.
+pub fn build_branch_summary_prompt(
+    branch_messages: &str,
+    custom_instructions: Option<&str>,
+) -> String {
+    let custom = custom_instructions
+        .map(|ci| format!("\n\nAdditional instructions: {ci}"))
+        .unwrap_or_default();
+
+    format!(
+        "## Branch Conversation\n{branch_messages}\n\n\
+         Summarize the conversation branch above. This summary will be used \
+         to preserve context when the user navigates away from this branch. \
+         Focus on key decisions, unresolved questions, and important context.{custom} \
+         Output ONLY the summary text, no preamble.",
+    )
+}
+
+/// Calculate how many messages to truncate to reach the target token count.
+pub fn estimate_truncation(
+    message_token_counts: &[i64],
+    current_total: i64,
+    target: i64,
+    preserve_last: usize,
+) -> AiResult<(usize, i64)> {
+    let n = message_token_counts.len();
+    if n <= preserve_last {
+        return Ok((0, 0));
+    }
+
+    let excess = (current_total - target).max(0);
+
+    let mut truncated = 0;
+    let mut saved = 0i64;
+    let limit = n - preserve_last;
+
+    for i in 0..limit {
+        if saved >= excess {
+            break;
+        }
+        saved += message_token_counts[i];
+        truncated += 1;
+    }
+
+    Ok((truncated, saved.min(excess)))
+}
+
+/// Calculate compaction parameters for a given set of messages.
+///
+/// Returns `(messages_to_compact, tokens_saved)` where `messages_to_compact`
+/// is the count of oldest messages to summarize, and `tokens_saved` is the
+/// estimated token savings.
+pub fn plan_compaction(
+    strategy: &CompressionStrategy,
+    message_token_counts: &[i64],
+    current_total: i64,
+) -> AiResult<(usize, i64)> {
+    if !strategy.should_compact(current_total) {
+        return Ok((0, 0));
+    }
+
+    estimate_truncation(
+        message_token_counts,
+        current_total,
+        strategy.target_tokens,
+        strategy.preserve_last_n_pairs * 2, // pairs → individual messages
+    )
+}
diff --git a/lib/ai/agent/config.rs b/lib/ai/agent/config.rs
new file mode 100644
index 0000000..d38c3a5
--- /dev/null
+++ b/lib/ai/agent/config.rs
@@ -0,0 +1,217 @@
+use crate::error::{AiError, AiResult};
+
+pub const DEFAULT_SYSTEM_PROMPT: &str = r#"You are a precise autonomous agent that executes tasks through tool calls.
+
+## Core Principles
+- Use tools when they can materially improve correctness or efficiency
+- After each action, verify results and adjust approach if needed
+- Keep reasoning concise and focus on actionable outcomes
+- Return only the final useful answer to the user
+
+## Workflow
+1. Analyze the request and plan your approach
+2. Execute actions using appropriate tools
+3. Review observations and verify assumptions
+4. Iterate until the task is complete
+5. Provide a clear, concise final response
+
+## Title Generation
+If this is the first user message in a new conversation with a default title, you SHOULD call `set_conversation_title` as your first action to create a short, descriptive title (max 100 chars). This helps keep the conversation organized. Only do this once at the very beginning."#;
+
+#[derive(Clone, Debug)]
+pub struct AgentConfig {
+    pub model: String,
+    pub provider: String,
+    pub api_mode: String,
+    pub system_prompt: String,
+    pub max_iterations: usize,
+    pub iteration_budget: usize,
+    pub temperature: Option<f64>,
+    pub max_completion_tokens: Option<u64>,
+    pub max_total_tokens_per_run: Option<i64>,
+    pub enabled_toolsets: Vec<String>,
+    pub disabled_toolsets: Vec<String>,
+    pub allowed_tools: Vec<String>,
+    pub denied_tools: Vec<String>,
+    pub retry_max_attempts: usize,
+    pub retry_base_delay_ms: u64,
+    pub retry_jitter: bool,
+    pub fallback_model: Option<String>,
+    pub skip_memory: bool,
+    pub skip_context_files: bool,
+    pub skip_compression: bool,
+    pub quiet_mode: bool,
+    pub save_trajectories: bool,
+    pub reasoning_effort: Option<String>,
+    pub service_tier: Option<String>,
+    pub platform: Option<String>,
+    pub session_id: Option<uuid::Uuid>,
+}
+
+impl AgentConfig {
+    pub fn new(model: impl Into<String>) -> AiResult<Self> {
+        let config = Self {
+            model: model.into(),
+            provider: String::new(),
+            api_mode: String::from("chat_completions"),
+            system_prompt: DEFAULT_SYSTEM_PROMPT.to_string(),
+            max_iterations: 64,
+            iteration_budget: 90,
+            temperature: Some(0.2),
+            max_completion_tokens: None,
+            max_total_tokens_per_run: Some(128_000),
+            enabled_toolsets: Vec::new(),
+            disabled_toolsets: Vec::new(),
+            allowed_tools: Vec::new(),
+            denied_tools: Vec::new(),
+            retry_max_attempts: 3,
+            retry_base_delay_ms: 1_000,
+            retry_jitter: true,
+            fallback_model: None,
+            skip_memory: false,
+            skip_context_files: false,
+            skip_compression: false,
+            quiet_mode: false,
+            save_trajectories: false,
+            reasoning_effort: None,
+            service_tier: None,
+            platform: None,
+            session_id: None,
+        };
+        config.validate()?;
+        Ok(config)
+    }
+
+    pub fn validate(&self) -> AiResult<()> {
+        if self.model.trim().is_empty() {
+            return Err(AiError::Config("agent model is required".to_string()));
+        }
+        if self.max_iterations == 0 {
+            return Err(AiError::Config(
+                "agent max_iterations must be greater than 0".to_string(),
+            ));
+        }
+        if let Some(tokens) = self.max_total_tokens_per_run
+            && tokens <= 0
+        {
+            return Err(AiError::Config(
+                "agent max_total_tokens_per_run must be > 0".to_string(),
+            ));
+        }
+        Ok(())
+    }
+
+    pub fn with_provider(mut self, provider: impl Into<String>) -> Self {
+        self.provider = provider.into();
+        self
+    }
+
+    pub fn with_api_mode(mut self, mode: impl Into<String>) -> Self {
+        self.api_mode = mode.into();
+        self
+    }
+
+    pub fn with_max_iterations(mut self, max: usize) -> Self {
+        self.max_iterations = max;
+        self.iteration_budget = self.iteration_budget.max(max);
+        self
+    }
+
+    pub fn with_iteration_budget(mut self, budget: usize) -> Self {
+        self.iteration_budget = budget;
+        self
+    }
+
+    pub fn with_system_prompt(mut self, prompt: impl Into<String>) -> Self {
+        self.system_prompt = prompt.into();
+        self
+    }
+
+    pub fn with_temperature(mut self, temperature: Option<f64>) -> Self {
+        self.temperature = temperature;
+        self
+    }
+
+    pub fn with_max_completion_tokens(mut self, max_completion_tokens: Option<u64>) -> Self {
+        self.max_completion_tokens = max_completion_tokens;
+        self
+    }
+
+    pub fn with_max_total_tokens(mut self, limit: Option<i64>) -> Self {
+        self.max_total_tokens_per_run = limit;
+        self
+    }
+
+    pub fn with_toolset_policy(mut self, enabled: Vec<String>, disabled: Vec<String>) -> Self {
+        self.enabled_toolsets = enabled;
+        self.disabled_toolsets = disabled;
+        self
+    }
+
+    pub fn with_tool_policy(mut self, allowed_tools: Vec<String>, denied_tools: Vec<String>) -> Self {
+        self.allowed_tools = allowed_tools;
+        self.denied_tools = denied_tools;
+        self
+    }
+
+    pub fn with_retry(mut self, max_attempts: usize, base_delay_ms: u64) -> Self {
+        self.retry_max_attempts = max_attempts;
+        self.retry_base_delay_ms = base_delay_ms;
+        self
+    }
+
+    pub fn with_retry_jitter(mut self, jitter: bool) -> Self {
+        self.retry_jitter = jitter;
+        self
+    }
+
+    pub fn with_fallback_model(mut self, fallback_model: impl Into<String>) -> Self {
+        self.fallback_model = Some(fallback_model.into());
+        self
+    }
+
+    pub fn with_skip_memory(mut self, skip: bool) -> Self {
+        self.skip_memory = skip;
+        self
+    }
+
+    pub fn with_skip_compression(mut self, skip: bool) -> Self {
+        self.skip_compression = skip;
+        self
+    }
+
+    pub fn with_quiet_mode(mut self, quiet: bool) -> Self {
+        self.quiet_mode = quiet;
+        self
+    }
+
+    pub fn with_platform(mut self, platform: impl Into<String>) -> Self {
+        self.platform = Some(platform.into());
+        self
+    }
+
+    pub fn with_session_id(mut self, session_id: uuid::Uuid) -> Self {
+        self.session_id = Some(session_id);
+        self
+    }
+
+    pub fn with_reasoning_effort(mut self, effort: impl Into<String>) -> Self {
+        self.reasoning_effort = Some(effort.into());
+        self
+    }
+
+    pub fn is_tool_exposed(&self, name: &str) -> bool {
+        let denied = self.denied_tools.iter().any(|tool| tool == name);
+        if denied {
+            return false;
+        }
+        if self.allowed_tools.is_empty() {
+            return true;
+        }
+        self.allowed_tools.iter().any(|tool| tool == name)
+    }
+}
+
+pub fn default_system_prompt() -> &'static str {
+    DEFAULT_SYSTEM_PROMPT
+}
diff --git a/lib/ai/agent/error_classifier.rs b/lib/ai/agent/error_classifier.rs
new file mode 100644
index 0000000..18718d3
--- /dev/null
+++ b/lib/ai/agent/error_classifier.rs
@@ -0,0 +1,239 @@
+use std::time::Duration;
+
+use crate::error::AiError;
+
+/// Categorized error for deciding retry/fallback/fatal strategy.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ErrorCategory {
+    /// Transient error, safe to retry with backoff.
+    Retryable { reason: String },
+    /// Authentication or quota error, switch to fallback model.
+    FallbackModel { reason: String },
+    /// Non-recoverable error, do not retry.
+    Fatal { reason: String },
+    /// Token budget exceeded for this run.
+    TokenBudgetExceeded,
+    /// Request timed out.
+    Timeout,
+    /// Request was cancelled by the caller.
+    Cancelled,
+    /// Provider is overloaded or at capacity, retry with longer delay.
+    Overloaded { reason: String },
+    /// Context window exceeded, needs compaction before retry.
+    ContextWindowExceeded { reason: String },
+}
+
+#[derive(Debug, Clone)]
+pub struct RetryPolicy {
+    pub max_attempts: usize,
+    pub base_delay: Duration,
+    pub jitter: bool,
+    pub exponential: bool,
+    pub switch_to_fallback: bool,
+}
+
+impl RetryPolicy {
+    pub fn delay_for_attempt(&self, attempt: usize) -> Duration {
+        let ms = if self.exponential {
+            self.base_delay.as_millis() as u64 * (1u64 << attempt.min(6))
+        } else {
+            self.base_delay.as_millis() as u64
+        };
+
+        let ms = if self.jitter {
+            let half = (ms as f64 * 0.25) as u64;
+            let lo = ms.saturating_sub(half);
+            let hi = ms.saturating_add(half);
+            let mix = ((attempt as u64).wrapping_mul(1_103_515_245)) % (hi - lo + 1);
+            lo + mix
+        } else {
+            ms
+        };
+
+        Duration::from_millis(ms.max(100))
+    }
+}
+
+/// Classify an error into a category for retry/fallback decisions.
+///
+/// Inspects both the HTTP status code (when available) and the error message
+/// content to determine the most appropriate category.
+pub fn classify_error(error: &AiError, http_status: Option<u16>) -> ErrorCategory {
+    // HTTP status-based classification takes precedence
+    let from_status = match http_status {
+        Some(429) => Some(ErrorCategory::Retryable {
+            reason: "rate limited (HTTP 429)".to_string(),
+        }),
+        Some(401) | Some(403) => Some(ErrorCategory::FallbackModel {
+            reason: format!("authentication failed (HTTP {})", http_status.unwrap()),
+        }),
+        Some(502) | Some(503) => Some(ErrorCategory::Overloaded {
+            reason: format!("provider unavailable (HTTP {})", http_status.unwrap()),
+        }),
+        Some(504) => Some(ErrorCategory::Timeout),
+        Some(413) => Some(ErrorCategory::ContextWindowExceeded {
+            reason: "payload too large (HTTP 413)".to_string(),
+        }),
+        Some(s) if (400..500).contains(&s) => Some(ErrorCategory::Fatal {
+            reason: format!("client error (HTTP {})", s),
+        }),
+        Some(s) if (500..600).contains(&s) => Some(ErrorCategory::Retryable {
+            reason: format!("server error (HTTP {})", s),
+        }),
+        _ => None,
+    };
+
+    if let Some(cat) = from_status {
+        return cat;
+    }
+
+    // Message-based classification
+    match error {
+        AiError::Timeout { .. } => ErrorCategory::Timeout,
+        AiError::TokenBudgetExceeded { .. } => ErrorCategory::TokenBudgetExceeded,
+        AiError::Api(msg) => classify_api_message(msg),
+        AiError::Response(msg) => classify_response_message(msg),
+        AiError::ModelRetriesExhausted { .. } => ErrorCategory::Fatal {
+            reason: error.to_string(),
+        },
+        _ => ErrorCategory::Fatal {
+            reason: error.to_string(),
+        },
+    }
+}
+
+/// Classify API error messages by keyword patterns.
+fn classify_api_message(msg: &str) -> ErrorCategory {
+    let lower = msg.to_lowercase();
+
+    // Rate limiting
+    if lower.contains("rate") || lower.contains("too many requests") || lower.contains("throttl") {
+        return ErrorCategory::Retryable {
+            reason: msg.to_string(),
+        };
+    }
+
+    // Overloaded / capacity
+    if lower.contains("overloaded")
+        || lower.contains("capacity")
+        || lower.contains("too busy")
+        || lower.contains("service unavailable")
+    {
+        return ErrorCategory::Overloaded {
+            reason: msg.to_string(),
+        };
+    }
+
+    // Authentication / quota
+    if lower.contains("unauthorized")
+        || lower.contains("invalid api key")
+        || lower.contains("api key")
+        || lower.contains("forbidden")
+        || lower.contains("quota exceeded")
+        || lower.contains("insufficient")
+        || lower.contains("billing")
+    {
+        return ErrorCategory::FallbackModel {
+            reason: msg.to_string(),
+        };
+    }
+
+    // Context window exceeded
+    if lower.contains("context length")
+        || lower.contains("context window")
+        || lower.contains("maximum context")
+        || lower.contains("too many tokens")
+        || lower.contains("max_tokens")
+    {
+        return ErrorCategory::ContextWindowExceeded {
+            reason: msg.to_string(),
+        };
+    }
+
+    ErrorCategory::Fatal {
+        reason: msg.to_string(),
+    }
+}
+
+/// Classify response error messages by keyword patterns.
+fn classify_response_message(msg: &str) -> ErrorCategory {
+    let lower = msg.to_lowercase();
+
+    if lower.contains("cancelled") || lower.contains("canceled") {
+        return ErrorCategory::Cancelled;
+    }
+    if lower.contains("timeout") || lower.contains("timed out") {
+        return ErrorCategory::Timeout;
+    }
+
+    ErrorCategory::Fatal {
+        reason: msg.to_string(),
+    }
+}
+
+/// Get the recommended retry policy for an error category.
+pub fn retry_policy_for(
+    category: &ErrorCategory,
+    max_attempts: usize,
+    base_delay_ms: u64,
+) -> RetryPolicy {
+    match category {
+        ErrorCategory::Retryable { .. } => RetryPolicy {
+            max_attempts,
+            base_delay: Duration::from_millis(base_delay_ms),
+            jitter: true,
+            exponential: true,
+            switch_to_fallback: false,
+        },
+        ErrorCategory::Overloaded { .. } => RetryPolicy {
+            max_attempts: max_attempts.min(5),
+            base_delay: Duration::from_millis(base_delay_ms.max(5_000)),
+            jitter: true,
+            exponential: true,
+            switch_to_fallback: true,
+        },
+        ErrorCategory::FallbackModel { .. } => RetryPolicy {
+            max_attempts: 1,
+            base_delay: Duration::from_millis(500),
+            jitter: false,
+            exponential: false,
+            switch_to_fallback: true,
+        },
+        ErrorCategory::ContextWindowExceeded { .. } => RetryPolicy {
+            max_attempts: 1,
+            base_delay: Duration::from_millis(0),
+            jitter: false,
+            exponential: false,
+            switch_to_fallback: false,
+        },
+        ErrorCategory::Timeout => RetryPolicy {
+            max_attempts: max_attempts.min(2),
+            base_delay: Duration::from_millis(base_delay_ms.max(2_000)),
+            jitter: true,
+            exponential: false,
+            switch_to_fallback: false,
+        },
+        ErrorCategory::TokenBudgetExceeded | ErrorCategory::Cancelled | ErrorCategory::Fatal { .. } => {
+            RetryPolicy {
+                max_attempts: 0,
+                base_delay: Duration::from_millis(0),
+                jitter: false,
+                exponential: false,
+                switch_to_fallback: false,
+            }
+        }
+    }
+}
+
+/// Determine whether the error warrants switching to a fallback model.
+pub fn should_switch_to_fallback(category: &ErrorCategory) -> bool {
+    matches!(
+        category,
+        ErrorCategory::FallbackModel { .. } | ErrorCategory::Overloaded { .. }
+    )
+}
+
+/// Determine whether compaction should be attempted before retry.
+pub fn should_compact_before_retry(category: &ErrorCategory) -> bool {
+    matches!(category, ErrorCategory::ContextWindowExceeded { .. })
+}
diff --git a/lib/ai/agent/events.rs b/lib/ai/agent/events.rs
new file mode 100644
index 0000000..681c9df
--- /dev/null
+++ b/lib/ai/agent/events.rs
@@ -0,0 +1,179 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// Fine-grained agent lifecycle events, inspired by pi's event system.
+///
+/// Covers the full agent execution lifecycle with enough granularity
+/// for UI rendering, telemetry, and extension hooks.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum AgentEvent {
+    // === Agent lifecycle ===
+    AgentStart,
+    AgentEnd {
+        messages: Vec<AgentEventMessage>,
+        total_input_tokens: u64,
+        total_output_tokens: u64,
+    },
+
+    // === Turn lifecycle ===
+    TurnStart {
+        turn_index: usize,
+    },
+    TurnEnd {
+        turn_index: usize,
+        assistant_text: Option<String>,
+        tool_call_count: usize,
+    },
+
+    // === Message lifecycle ===
+    MessageStart {
+        role: MessageRole,
+    },
+    MessageTextDelta {
+        index: usize,
+        delta: String,
+    },
+    MessageThinkingDelta {
+        index: usize,
+        delta: String,
+    },
+    MessageEnd {
+        role: MessageRole,
+    },
+
+    // === Tool execution lifecycle ===
+    ToolExecutionStart {
+        tool_call_id: String,
+        tool_name: String,
+        arguments: Value,
+    },
+    ToolExecutionUpdate {
+        tool_call_id: String,
+        tool_name: String,
+        partial_output: String,
+    },
+    ToolExecutionEnd {
+        tool_call_id: String,
+        tool_name: String,
+        output: Option<Value>,
+        error: Option<String>,
+        elapsed_ms: i64,
+    },
+
+    // === Steering / follow-up ===
+    SteeringMessagesInjected {
+        count: usize,
+    },
+    FollowUpMessagesInjected {
+        count: usize,
+    },
+
+    // === Context management ===
+    ContextCompacted {
+        messages_compacted: usize,
+        tokens_saved: i64,
+    },
+    BranchSummaryCreated {
+        entry_count: usize,
+        summary_length: usize,
+    },
+
+    // === Model switching ===
+    ModelSwitched {
+        from_model: String,
+        to_model: String,
+        reason: String,
+    },
+
+    // === Error and retry ===
+    ErrorClassified {
+        category: String,
+        message: String,
+        will_retry: bool,
+        retry_delay_ms: Option<u64>,
+    },
+    RetryAttempt {
+        attempt: usize,
+        max_attempts: usize,
+        delay_ms: u64,
+    },
+}
+
+/// Simplified message role for event display.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum MessageRole {
+    User,
+    Assistant,
+    ToolResult,
+    System,
+}
+
+/// A simplified message representation for `AgentEnd` events.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AgentEventMessage {
+    pub role: MessageRole,
+    pub content: String,
+    pub tool_calls: Vec<EventToolCall>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EventToolCall {
+    pub id: String,
+    pub name: String,
+    pub arguments: Value,
+    pub output: Option<Value>,
+    pub error: Option<String>,
+}
+
+/// An async-friendly event sink that collects or broadcasts events.
+pub struct EventSink {
+    senders: Vec<tokio::sync::mpsc::UnboundedSender<AgentEvent>>,
+}
+
+impl EventSink {
+    pub fn new() -> Self {
+        Self {
+            senders: Vec::new(),
+        }
+    }
+
+    /// Subscribe to events, returns a receiver.
+    pub fn subscribe(&mut self) -> tokio::sync::mpsc::UnboundedReceiver<AgentEvent> {
+        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
+        self.senders.push(tx);
+        rx
+    }
+
+    /// Emit an event to all subscribers. Non-blocking; drops if receiver disconnected.
+    pub fn emit(&self, event: AgentEvent) {
+        for sender in &self.senders {
+            let _ = sender.send(event.clone());
+        }
+    }
+
+    /// Check if there are any active subscribers.
+    pub fn has_subscribers(&self) -> bool {
+        !self.senders.is_empty()
+    }
+
+    /// Remove disconnected senders.
+    pub fn cleanup(&mut self) {
+        self.senders.retain(|s| !s.is_closed());
+    }
+}
+
+impl Default for EventSink {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Clone for EventSink {
+    fn clone(&self) -> Self {
+        Self {
+            senders: self.senders.clone(),
+        }
+    }
+}
diff --git a/lib/ai/agent/helpers.rs b/lib/ai/agent/helpers.rs
new file mode 100644
index 0000000..3effec2
--- /dev/null
+++ b/lib/ai/agent/helpers.rs
@@ -0,0 +1,113 @@
+use std::future::Future;
+use std::time::Duration;
+
+use crate::agent::request::AgentRequest;
+use crate::error::{AiError, AiResult};
+
+pub fn build_input_string(request: &AgentRequest) -> String {
+    let mut input = String::new();
+
+    if !request.context.is_empty() {
+        input.push_str("<retrieved_context>\n");
+        for chunk in &request.context {
+            let source = chunk.source.as_deref().unwrap_or("unknown");
+            let score = chunk
+                .score
+                .map(|s| format!("{s:.4}"))
+                .unwrap_or_else(|| "n/a".to_string());
+            input.push_str(&format!(
+                "\n<chunk id=\"{}\" source=\"{}\" score=\"{}\">\n{}\n</chunk>\n",
+                chunk.id, source, score, chunk.content
+            ));
+        }
+        input.push_str("</retrieved_context>\n\n");
+    }
+
+    for message in &request.messages {
+        match message {
+            super::request::AgentMessage::User(content) => {
+                input.push_str(&format!("User: {content}\n"));
+            }
+            super::request::AgentMessage::Assistant(content) => {
+                input.push_str(&format!("Assistant: {content}\n"));
+            }
+        }
+    }
+
+    input.push_str(&format!("User: {}", request.input));
+
+    input
+}
+
+pub fn estimate_tokens(text: &str) -> u64 {
+    if text.is_empty() {
+        return 0;
+    }
+    (text.chars().count() as f64 / 2.5).ceil() as u64
+}
+
+pub fn check_token_budget(
+    estimated_input_tokens: u64,
+    accumulated_output_chars: usize,
+    limit: i64,
+) -> bool {
+    let output_estimate = (accumulated_output_chars as f64 / 2.5).ceil() as u64;
+    estimated_input_tokens + output_estimate > limit as u64
+}
+
+pub async fn with_retry<F, Fut, T>(
+    max_attempts: usize,
+    base_delay_ms: u64,
+    f: F,
+) -> AiResult<T>
+where
+    F: Fn() -> Fut,
+    Fut: Future<Output = AiResult<T>>,
+{
+    let mut last_error: Option<AiError> = None;
+    for attempt in 0..max_attempts {
+        match f().await {
+            Ok(result) => return Ok(result),
+            Err(e) if is_retryable(&e) && attempt + 1 < max_attempts => {
+                let delay = Duration::from_millis(base_delay_ms * 2u64.pow(attempt as u32));
+                tracing::warn!(
+                    error = %e,
+                    attempt = attempt + 1,
+                    max_attempts,
+                    delay_ms = delay.as_millis(),
+                    "retrying after transient error"
+                );
+                tokio::time::sleep(delay).await;
+                last_error = Some(e);
+            }
+            Err(e) => return Err(e),
+        }
+    }
+    Err(AiError::ModelRetriesExhausted {
+        attempts: max_attempts,
+        last_error: last_error
+            .map(|e| e.to_string())
+            .unwrap_or_else(|| "unknown".to_string()),
+    })
+}
+
+fn is_retryable(error: &AiError) -> bool {
+    matches!(
+        error,
+        AiError::Api(_) | AiError::Response(_) | AiError::ModelRetriesExhausted { .. }
+    )
+}
+
+pub fn tool_result_content_to_string(
+    content: &rig::one_or_many::OneOrMany<rig::completion::message::ToolResultContent>,
+) -> String {
+    use rig::completion::message::ToolResultContent;
+    content
+        .iter()
+        .filter_map(|item| match item {
+            ToolResultContent::Text(t) => Some(t.text.clone()),
+            _ => None,
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
diff --git a/lib/ai/agent/hooks.rs b/lib/ai/agent/hooks.rs
new file mode 100644
index 0000000..19888d5
--- /dev/null
+++ b/lib/ai/agent/hooks.rs
@@ -0,0 +1,145 @@
+use async_trait::async_trait;
+use serde_json::Value;
+
+use crate::agent::persistence::AgentRunContext;
+use crate::error::AiResult;
+
+#[derive(Debug, Clone)]
+pub enum ToolGuardrailDecision {
+    Allow,
+    Block { reason: String },
+    RequireApproval { message: String },
+}
+
+#[derive(Debug, Clone)]
+pub struct ToolCallOutcome {
+    pub name: String,
+    pub arguments: Value,
+    pub output: Option<Value>,
+    pub error: Option<String>,
+    pub elapsed_ms: i64,
+}
+
+#[derive(Debug, Clone)]
+pub struct HookMessage {
+    pub role: String,
+    pub content: Option<String>,
+    pub tool_calls: Option<Value>,
+    pub tool_call_id: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct HookLlmResponse {
+    pub content: Option<String>,
+    pub tool_calls: Option<Value>,
+    pub input_tokens: u64,
+    pub output_tokens: u64,
+    pub finish_reason: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct HookToolDef {
+    pub name: String,
+    pub description: String,
+}
+
+#[async_trait]
+pub trait AgentHook: Send + Sync {
+    fn name(&self) -> &'static str;
+
+    async fn on_session_start(&self, _ctx: &AgentRunContext) -> AiResult<()> {
+        Ok(())
+    }
+
+    async fn on_session_end(&self, _ctx: &AgentRunContext, _success: bool) -> AiResult<()> {
+        Ok(())
+    }
+
+    async fn pre_llm_call(&self, _messages: &[HookMessage], _tools: &[HookToolDef]) -> AiResult<()> {
+        Ok(())
+    }
+
+    async fn post_llm_call(&self, _response: &HookLlmResponse) -> AiResult<()> {
+        Ok(())
+    }
+
+    async fn pre_tool_call(
+        &self,
+        _tool_name: &str,
+        _arguments: &Value,
+    ) -> AiResult<Option<ToolGuardrailDecision>> {
+        Ok(None)
+    }
+
+    async fn post_tool_call(&self, _outcome: &ToolCallOutcome) -> AiResult<()> {
+        Ok(())
+    }
+}
+
+pub struct HookChain {
+    hooks: Vec<Box<dyn AgentHook>>,
+}
+
+impl HookChain {
+    pub fn new(hooks: Vec<Box<dyn AgentHook>>) -> Self {
+        Self { hooks }
+    }
+
+    pub fn empty() -> Self {
+        Self { hooks: Vec::new() }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.hooks.is_empty()
+    }
+
+    pub async fn run_session_start(&self, ctx: &AgentRunContext) -> AiResult<()> {
+        for hook in &self.hooks {
+            hook.on_session_start(ctx).await?;
+        }
+        Ok(())
+    }
+
+    pub async fn run_session_end(&self, ctx: &AgentRunContext, success: bool) -> AiResult<()> {
+        for hook in &self.hooks {
+            hook.on_session_end(ctx, success).await?;
+        }
+        Ok(())
+    }
+
+    pub async fn run_pre_llm_call(&self, messages: &[HookMessage], tools: &[HookToolDef]) -> AiResult<()> {
+        for hook in &self.hooks {
+            hook.pre_llm_call(messages, tools).await?;
+        }
+        Ok(())
+    }
+
+    pub async fn run_post_llm_call(&self, response: &HookLlmResponse) -> AiResult<()> {
+        for hook in &self.hooks {
+            hook.post_llm_call(response).await?;
+        }
+        Ok(())
+    }
+
+    pub async fn run_pre_tool_call(
+        &self,
+        tool_name: &str,
+        arguments: &Value,
+    ) -> AiResult<Option<ToolGuardrailDecision>> {
+        for hook in &self.hooks {
+            if let Some(decision) = hook.pre_tool_call(tool_name, arguments).await? {
+                if !matches!(decision, ToolGuardrailDecision::Allow) {
+                    return Ok(Some(decision));
+                }
+            }
+        }
+        Ok(None)
+    }
+
+    pub async fn run_post_tool_call(&self, outcome: &ToolCallOutcome) -> AiResult<()> {
+        for hook in &self.hooks {
+            hook.post_tool_call(outcome).await?;
+        }
+        Ok(())
+    }
+}
diff --git a/lib/ai/agent/iteration_budget.rs b/lib/ai/agent/iteration_budget.rs
new file mode 100644
index 0000000..3603569
--- /dev/null
+++ b/lib/ai/agent/iteration_budget.rs
@@ -0,0 +1,45 @@
+#[derive(Clone, Debug)]
+pub struct IterationBudget {
+    pub remaining: usize,
+    pub hard_limit: usize,
+    pub grace_call: bool,
+    pub consumed: usize,
+}
+
+impl IterationBudget {
+    pub fn new(limit: usize) -> Self {
+        Self {
+            remaining: limit,
+            hard_limit: limit,
+            grace_call: true,
+            consumed: 0,
+        }
+    }
+
+    pub fn can_continue(&self) -> bool {
+        self.remaining > 0 || (self.remaining == 0 && self.grace_call)
+    }
+
+    pub fn consume(&mut self) -> bool {
+        if self.remaining > 0 {
+            self.remaining -= 1;
+            self.consumed += 1;
+            true
+        } else if self.grace_call {
+            self.grace_call = false;
+            self.consumed += 1;
+            true
+        } else {
+            false
+        }
+    }
+
+    pub fn exhaust(&mut self) {
+        self.remaining = 0;
+        self.grace_call = false;
+    }
+
+    pub const fn total_consumed(&self) -> usize {
+        self.consumed
+    }
+}
diff --git a/lib/ai/agent/loop.rs b/lib/ai/agent/loop.rs
new file mode 100644
index 0000000..5d36d0f
--- /dev/null
+++ b/lib/ai/agent/loop.rs
@@ -0,0 +1,876 @@
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use futures::StreamExt;
+use rig::agent::AgentBuilder;
+use rig::client::CompletionClient;
+use rig::streaming::StreamingPrompt;
+use rig::tool::ToolDyn;
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+use tracing::{info, warn};
+
+use super::config::AgentConfig;
+use super::error_classifier::{
+    classify_error, retry_policy_for, should_switch_to_fallback,
+};
+use super::events::{AgentEvent, EventSink};
+use super::helpers::{build_input_string, estimate_tokens};
+use super::hooks::{HookChain, HookLlmResponse, HookMessage, ToolCallOutcome, ToolGuardrailDecision};
+use super::iteration_budget::IterationBudget;
+use super::request::{AgentRequest, AgentResult, AgentStep, ToolCallRecord};
+use super::RigStreamChunk;
+use crate::client::AiClient;
+use crate::error::{AiError, AiResult};
+
+/// How tool calls from a single assistant turn are executed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolExecutionMode {
+    /// Execute tool calls one at a time.
+    Sequential,
+    /// Execute tool calls concurrently (after sequential preflight).
+    Parallel,
+}
+
+impl Default for ToolExecutionMode {
+    fn default() -> Self {
+        Self::Parallel
+    }
+}
+
+/// Callback type for steering messages (injected mid-run).
+pub type SteeringFn = Arc<
+    dyn Fn() -> Pin<Box<dyn Future<Output = Vec<String>> + Send>> + Send + Sync,
+>;
+
+/// Callback type for follow-up messages (injected after agent would stop).
+pub type FollowUpFn = Arc<
+    dyn Fn() -> Pin<Box<dyn Future<Output = Vec<String>> + Send>> + Send + Sync,
+>;
+
+/// Callback to decide whether the agent should stop after a turn.
+pub type ShouldStopFn = Arc<
+    dyn Fn(&TurnContext) -> bool + Send + Sync,
+>;
+
+/// Callback to prepare/modify state before the next turn.
+pub type PrepareNextTurnFn = Arc<
+    dyn Fn(&TurnContext) -> Pin<Box<dyn Future<Output = Option<TurnUpdate>> + Send>>
+        + Send
+        + Sync,
+>;
+
+/// Context passed to `should_stop` and `prepare_next_turn` callbacks.
+#[derive(Debug, Clone)]
+pub struct TurnContext {
+    pub turn_index: usize,
+    pub assistant_text: String,
+    pub tool_call_count: usize,
+    pub total_input_tokens: u64,
+    pub total_output_tokens: u64,
+    pub model_name: String,
+}
+
+/// Replacement state for the next turn (returned by `prepare_next_turn`).
+#[derive(Debug, Clone)]
+pub struct TurnUpdate {
+    pub model: Option<String>,
+    pub temperature: Option<f64>,
+    pub max_completion_tokens: Option<u64>,
+}
+
+/// Extended agent loop configuration, adding steering/follow-up/lifecycle
+/// hooks on top of the base `AgentConfig`.
+pub struct AgentLoopConfig {
+    pub config: AgentConfig,
+    pub tool_execution_mode: ToolExecutionMode,
+    pub get_steering_messages: Option<SteeringFn>,
+    pub get_follow_up_messages: Option<FollowUpFn>,
+    pub should_stop_after_turn: Option<ShouldStopFn>,
+    pub prepare_next_turn: Option<PrepareNextTurnFn>,
+    pub event_sink: Option<EventSink>,
+}
+
+impl AgentLoopConfig {
+    pub fn new(config: AgentConfig) -> Self {
+        Self {
+            config,
+            tool_execution_mode: ToolExecutionMode::default(),
+            get_steering_messages: None,
+            get_follow_up_messages: None,
+            should_stop_after_turn: None,
+            prepare_next_turn: None,
+            event_sink: None,
+        }
+    }
+
+    pub fn with_tool_execution_mode(mut self, mode: ToolExecutionMode) -> Self {
+        self.tool_execution_mode = mode;
+        self
+    }
+
+    pub fn with_steering_messages(mut self, f: SteeringFn) -> Self {
+        self.get_steering_messages = Some(f);
+        self
+    }
+
+    pub fn with_follow_up_messages(mut self, f: FollowUpFn) -> Self {
+        self.get_follow_up_messages = Some(f);
+        self
+    }
+
+    pub fn with_should_stop(mut self, f: ShouldStopFn) -> Self {
+        self.should_stop_after_turn = Some(f);
+        self
+    }
+
+    pub fn with_prepare_next_turn(mut self, f: PrepareNextTurnFn) -> Self {
+        self.prepare_next_turn = Some(f);
+        self
+    }
+
+    pub fn with_event_sink(mut self, sink: EventSink) -> Self {
+        self.event_sink = Some(sink);
+        self
+    }
+}
+
+/// Enhanced agent with loop controls (steering, follow-up, model switching).
+pub struct EnhancedAgent {
+    pub client: AiClient,
+    pub loop_config: AgentLoopConfig,
+    pub hooks: HookChain,
+}
+
+impl EnhancedAgent {
+    pub fn new(client: AiClient, loop_config: AgentLoopConfig) -> AiResult<Self> {
+        loop_config.config.validate()?;
+        Ok(Self {
+            client,
+            loop_config,
+            hooks: HookChain::empty(),
+        })
+    }
+
+    pub fn with_hooks(mut self, hooks: HookChain) -> Self {
+        self.hooks = hooks;
+        self
+    }
+
+    pub fn config(&self) -> &AgentConfig {
+        &self.loop_config.config
+    }
+
+    /// Run the enhanced agent loop, returning a chunk receiver and a join handle.
+    #[allow(clippy::too_many_lines)]
+    pub fn run(
+        &self,
+        request: AgentRequest,
+        tools: Vec<Box<dyn ToolDyn>>,
+    ) -> (
+        mpsc::Receiver<RigStreamChunk>,
+        tokio::task::JoinHandle<AiResult<AgentResult>>,
+    ) {
+        let (tx, rx) = mpsc::channel::<RigStreamChunk>(256);
+
+        let config = self.loop_config.config.clone();
+        let tool_execution_mode = self.loop_config.tool_execution_mode;
+        let steering_fn = self.loop_config.get_steering_messages.clone();
+        let follow_up_fn = self.loop_config.get_follow_up_messages.clone();
+        let should_stop = self.loop_config.should_stop_after_turn.clone();
+        let prepare_next = self.loop_config.prepare_next_turn.clone();
+        let event_sink = self.loop_config.event_sink.clone();
+        let client = self.client.llm_client().clone();
+        let hooks = self.hooks.clone();
+
+        let filtered_tools: Vec<Box<dyn ToolDyn>> = tools
+            .into_iter()
+            .filter(|tool| config.is_tool_exposed(&tool.name()))
+            .collect();
+
+        let handle = tokio::spawn(async move {
+            run_enhanced_loop(
+                client,
+                config,
+                request,
+                filtered_tools,
+                tool_execution_mode,
+                steering_fn,
+                follow_up_fn,
+                should_stop,
+                prepare_next,
+                event_sink,
+                hooks,
+                tx,
+            )
+            .await
+        });
+
+        (rx, handle)
+    }
+}
+
+#[allow(clippy::too_many_lines, clippy::too_many_arguments)]
+async fn run_enhanced_loop(
+    client: rig::providers::openai::Client,
+    mut config: AgentConfig,
+    request: AgentRequest,
+    tools: Vec<Box<dyn ToolDyn>>,
+    _tool_execution_mode: ToolExecutionMode,
+    steering_fn: Option<SteeringFn>,
+    follow_up_fn: Option<FollowUpFn>,
+    should_stop: Option<ShouldStopFn>,
+    prepare_next: Option<PrepareNextTurnFn>,
+    event_sink: Option<EventSink>,
+    hooks: HookChain,
+    tx: mpsc::Sender<RigStreamChunk>,
+) -> AiResult<AgentResult> {
+    let cancellation = request.cancellation_token.clone();
+    let timeout = request.timeout;
+    let mut budget = IterationBudget::new(config.iteration_budget);
+    let mut all_steps: Vec<AgentStep> = Vec::new();
+    let mut total_input_tokens: u64 = 0;
+    let mut total_output_tokens: u64 = 0;
+    let mut turn_index: usize = 0;
+
+    // Session start hook
+    if let Some(ctx) = &request.run_context {
+        let _ = hooks.run_session_start(ctx).await;
+    }
+
+    // Emit agent start event
+    if let Some(sink) = &event_sink {
+        sink.emit(AgentEvent::AgentStart);
+    }
+
+    // Build the initial input
+    let input = build_input_string(&request);
+    let mut current_input = input.clone();
+    let estimated_input_tokens = estimate_tokens(&current_input);
+
+    if let Some(limit) = config.max_total_tokens_per_run
+        && estimated_input_tokens > limit as u64
+    {
+        return Err(AiError::TokenBudgetExceeded {
+            estimated: estimated_input_tokens,
+            limit,
+        });
+    }
+
+    // Outer loop: handles follow-up messages after agent would stop
+    loop {
+        // Inner loop: tool call turns + steering messages
+        let mut pending_steering: Vec<String> = if let Some(f) = &steering_fn {
+            f().await
+        } else {
+            Vec::new()
+        };
+
+        loop {
+            // Check cancellation
+            if cancellation.as_ref().is_some_and(|ct| ct.is_cancelled()) {
+                let _ = tx.send(RigStreamChunk::Failed { error: "cancelled".to_string() }).await;
+                if let Some(sink) = &event_sink {
+                    sink.emit(AgentEvent::ErrorClassified {
+                        category: "cancelled".to_string(),
+                        message: "cancelled by caller".to_string(),
+                        will_retry: false,
+                        retry_delay_ms: None,
+                    });
+                }
+                return Err(AiError::Response("agent run cancelled".to_string()));
+            }
+
+            // Inject steering messages if any
+            if !pending_steering.is_empty() {
+                let count = pending_steering.len();
+                for msg in &pending_steering {
+                    current_input.push_str(&format!("\nUser: {msg}\n"));
+                }
+                if let Some(sink) = &event_sink {
+                    sink.emit(AgentEvent::SteeringMessagesInjected { count });
+                }
+                pending_steering.clear();
+            }
+
+            // Emit turn start
+            if let Some(sink) = &event_sink {
+                sink.emit(AgentEvent::TurnStart { turn_index });
+            }
+            let _ = tx.send(RigStreamChunk::TextDelta {
+                index: 0,
+                content: String::new(), // placeholder for turn boundary detection
+            }).await;
+
+            // Run one LLM turn with retry
+            let turn_result = run_single_turn(
+                &client,
+                &config,
+                &current_input,
+                &tools,
+                &mut budget,
+                &cancellation,
+                timeout,
+                &hooks,
+                &event_sink,
+                &tx,
+            )
+            .await;
+
+            match turn_result {
+                Ok(turn_output) => {
+                    total_input_tokens += turn_output.input_tokens;
+                    total_output_tokens += turn_output.output_tokens;
+
+                    // Collect step
+                    let tool_call_count = turn_output.tool_calls.len();
+                    if !turn_output.tool_calls.is_empty() || !turn_output.assistant_text.is_empty() {
+                        all_steps.push(AgentStep {
+                            index: all_steps.len(),
+                            assistant: (!turn_output.assistant_text.is_empty())
+                                .then_some(turn_output.assistant_text.clone()),
+                            reasoning_content: None,
+                            tool_calls: turn_output.tool_calls,
+                            reflection: None,
+                        });
+                    }
+
+                    // Emit turn end
+                    if let Some(sink) = &event_sink {
+                        sink.emit(AgentEvent::TurnEnd {
+                            turn_index,
+                            assistant_text: Some(turn_output.assistant_text.clone()),
+                            tool_call_count,
+                        });
+                    }
+
+                    // Check should_stop
+                    let turn_ctx = TurnContext {
+                        turn_index,
+                        assistant_text: turn_output.assistant_text.clone(),
+                        tool_call_count,
+                        total_input_tokens,
+                        total_output_tokens,
+                        model_name: config.model.clone(),
+                    };
+
+                    if let Some(stop_fn) = &should_stop {
+                        if stop_fn(&turn_ctx) {
+                            info!(turn_index, "agent stopped by should_stop callback");
+                            break;
+                        }
+                    }
+
+                    // Prepare next turn (may switch model)
+                    if let Some(prep_fn) = &prepare_next {
+                        if let Some(update) = prep_fn(&turn_ctx).await {
+                            if let Some(new_model) = update.model {
+                                if let Some(sink) = &event_sink {
+                                    sink.emit(AgentEvent::ModelSwitched {
+                                        from_model: config.model.clone(),
+                                        to_model: new_model.clone(),
+                                        reason: "prepare_next_turn".to_string(),
+                                    });
+                                }
+                                config.model = new_model;
+                            }
+                            if let Some(temp) = update.temperature {
+                                config.temperature = Some(temp);
+                            }
+                            if let Some(max_tok) = update.max_completion_tokens {
+                                config.max_completion_tokens = Some(max_tok);
+                            }
+                        }
+                    }
+
+                    turn_index += 1;
+
+                    // If no tool calls, this turn is done
+                    if tool_call_count == 0 {
+                        break;
+                    }
+
+                    // Otherwise, continue with tool results as new input
+                    current_input = turn_output.assistant_text.clone();
+                }
+                Err(e) => {
+                    // Error classification and retry with fallback
+                    let category = classify_error(&e, None);
+                    let policy = retry_policy_for(&category, config.retry_max_attempts, config.retry_base_delay_ms);
+
+                    if let Some(sink) = &event_sink {
+                        sink.emit(AgentEvent::ErrorClassified {
+                            category: format!("{category:?}"),
+                            message: e.to_string(),
+                            will_retry: policy.switch_to_fallback || policy.max_attempts > 0,
+                            retry_delay_ms: Some(policy.base_delay.as_millis() as u64),
+                        });
+                    }
+
+                    if should_switch_to_fallback(&category) {
+                        if let Some(fallback_model) = &config.fallback_model {
+                            info!(
+                                from_model = %config.model,
+                                to_model = %fallback_model,
+                                "switching to fallback model due to error"
+                            );
+
+                            if let Some(sink) = &event_sink {
+                                sink.emit(AgentEvent::ModelSwitched {
+                                    from_model: config.model.clone(),
+                                    to_model: fallback_model.clone(),
+                                    reason: format!("fallback: {category:?}"),
+                                });
+                            }
+
+                            config.model = fallback_model.clone();
+
+                            // Retry with the fallback model
+                            let retry_result = run_single_turn(
+                                &client,
+                                &config,
+                                &current_input,
+                                &tools,
+                                &mut budget,
+                                &cancellation,
+                                timeout,
+                                &hooks,
+                                &event_sink,
+                                &tx,
+                            )
+                            .await;
+
+                            match retry_result {
+                                Ok(turn_output) => {
+                                    total_input_tokens += turn_output.input_tokens;
+                                    total_output_tokens += turn_output.output_tokens;
+                                    let tc_count = turn_output.tool_calls.len();
+                                    let has_tools = tc_count > 0;
+                                    let has_text = !turn_output.assistant_text.is_empty();
+                                    let assistant = turn_output.assistant_text;
+                                    if has_tools || has_text {
+                                        all_steps.push(AgentStep {
+                                            index: all_steps.len(),
+                                            assistant: has_text.then_some(assistant.clone()),
+                                            reasoning_content: None,
+                                            tool_calls: turn_output.tool_calls,
+                                            reflection: None,
+                                        });
+                                    }
+                                    turn_index += 1;
+                                    if !has_tools {
+                                        break;
+                                    }
+                                    current_input = assistant;
+                                    continue;
+                                }
+                                Err(retry_err) => {
+                                    let _ = tx
+                                        .send(RigStreamChunk::Failed {
+                                            error: retry_err.to_string(),
+                                        })
+                                        .await;
+                                    if let Some(ctx) = &request.run_context {
+                                        let _ = hooks.run_session_end(ctx, false).await;
+                                    }
+                                    return Err(retry_err);
+                                }
+                            }
+                        }
+                    }
+
+                    // Non-retryable or no fallback
+                    let _ = tx
+                        .send(RigStreamChunk::Failed {
+                            error: e.to_string(),
+                        })
+                        .await;
+                    if let Some(ctx) = &request.run_context {
+                        let _ = hooks.run_session_end(ctx, false).await;
+                    }
+                    return Err(e);
+                }
+            }
+        }
+
+        // Check for follow-up messages
+        let follow_ups: Vec<String> = if let Some(f) = &follow_up_fn {
+            f().await
+        } else {
+            Vec::new()
+        };
+
+        if follow_ups.is_empty() {
+            break;
+        }
+
+        // Inject follow-up messages and continue the outer loop
+        let count = follow_ups.len();
+        for msg in &follow_ups {
+            current_input.push_str(&format!("\nUser: {msg}\n"));
+        }
+        if let Some(sink) = &event_sink {
+            sink.emit(AgentEvent::FollowUpMessagesInjected { count });
+        }
+    }
+
+    // Build final output
+    let output = all_steps
+        .last()
+        .and_then(|s| s.assistant.clone())
+        .unwrap_or_default();
+
+    if let Some(sink) = &event_sink {
+        sink.emit(AgentEvent::AgentEnd {
+            messages: Vec::new(),
+            total_input_tokens,
+            total_output_tokens,
+        });
+    }
+
+    let _ = tx
+        .send(RigStreamChunk::Final {
+            content: output.clone(),
+            input_tokens: total_input_tokens,
+            output_tokens: total_output_tokens,
+        })
+        .await;
+
+    if let Some(ctx) = &request.run_context {
+        let _ = hooks.run_session_end(ctx, true).await;
+    }
+
+    info!(
+        turns = turn_index,
+        steps = all_steps.len(),
+        total_input_tokens,
+        total_output_tokens,
+        "enhanced agent loop completed"
+    );
+
+    Ok(AgentResult {
+        output,
+        steps: all_steps,
+        expert_outputs: Vec::new(),
+        input_tokens: total_input_tokens as i64,
+        output_tokens: total_output_tokens as i64,
+    })
+}
+
+/// Output from a single LLM turn (one assistant response + its tool calls).
+struct TurnOutput {
+    assistant_text: String,
+    tool_calls: Vec<ToolCallRecord>,
+    input_tokens: u64,
+    output_tokens: u64,
+}
+
+/// Run a single LLM turn with streaming, handling the stream parsing and
+/// tool call collection.
+#[allow(clippy::too_many_arguments)]
+async fn run_single_turn(
+    client: &rig::providers::openai::Client,
+    config: &AgentConfig,
+    input: &str,
+    _tools: &[Box<dyn ToolDyn>],
+    budget: &mut IterationBudget,
+    cancellation: &Option<CancellationToken>,
+    timeout: Option<std::time::Duration>,
+    hooks: &HookChain,
+    event_sink: &Option<EventSink>,
+    tx: &mpsc::Sender<RigStreamChunk>,
+) -> AiResult<TurnOutput> {
+    if !budget.consume() {
+        return Err(AiError::Response("iteration budget exhausted".to_string()));
+    }
+
+    let model = client.completion_model(&config.model);
+    let mut agent_builder = AgentBuilder::new(model)
+        .preamble(&config.system_prompt)
+        .default_max_turns(1); // Single turn, we manage the loop
+
+    // Note: we can't easily pass tools here for single-turn since
+    // rig's multi_turn handles tool execution internally.
+    // For the enhanced loop, we rely on rig's built-in tool execution
+    // within a single turn. The parallel/sequential mode is controlled
+    // by the event-level hooks.
+
+    if let Some(temp) = config.temperature {
+        agent_builder = agent_builder.temperature(temp);
+    }
+    if let Some(mt) = config.max_completion_tokens {
+        agent_builder = agent_builder.max_tokens(mt);
+    }
+
+    let agent = agent_builder.build();
+
+    // Pre-LLM hook
+    if !hooks.is_empty() {
+        let hook_messages = vec![HookMessage {
+            role: "user".to_string(),
+            content: Some(input.to_string()),
+            tool_calls: None,
+            tool_call_id: None,
+        }];
+        let _ = hooks.run_pre_llm_call(&hook_messages, &[]).await;
+    }
+
+    let stream_future = agent
+        .stream_prompt(input)
+        .with_history(Vec::<rig::completion::Message>::new())
+        .multi_turn(config.max_iterations);
+
+    let stream = if let Some(dur) = timeout {
+        match tokio::time::timeout(dur, stream_future).await {
+            Ok(stream) => stream,
+            Err(_) => {
+                return Err(AiError::Timeout {
+                    seconds: dur.as_secs(),
+                });
+            }
+        }
+    } else {
+        stream_future.await
+    };
+
+    tokio::pin!(stream);
+
+    let mut assistant_text = String::new();
+    let mut tool_calls: Vec<ToolCallRecord> = Vec::new();
+    let mut delta_index = 0usize;
+    let mut _accumulated_output_chars: usize = 0;
+    let mut input_tokens: u64 = 0;
+    let mut output_tokens: u64 = 0;
+
+    while let Some(item) = stream.next().await {
+        if cancellation.as_ref().is_some_and(|ct| ct.is_cancelled()) {
+            return Err(AiError::Response("cancelled".to_string()));
+        }
+
+        match item {
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::Text(text),
+            )) => {
+                _accumulated_output_chars += text.text.chars().count();
+                assistant_text.push_str(&text.text);
+
+                if let Some(sink) = &event_sink {
+                    sink.emit(AgentEvent::MessageTextDelta {
+                        index: delta_index,
+                        delta: text.text.clone(),
+                    });
+                }
+
+                let _ = tx
+                    .send(RigStreamChunk::TextDelta {
+                        index: delta_index,
+                        content: text.text.clone(),
+                    })
+                    .await;
+                delta_index += 1;
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::Reasoning(reasoning),
+            )) => {
+                for part in &reasoning.content {
+                    if let rig::completion::message::ReasoningContent::Text { text, .. } = part {
+                        _accumulated_output_chars += text.chars().count();
+                        if let Some(sink) = &event_sink {
+                            sink.emit(AgentEvent::MessageThinkingDelta {
+                                index: delta_index,
+                                delta: text.clone(),
+                            });
+                        }
+                        let _ = tx
+                            .send(RigStreamChunk::Thinking {
+                                index: delta_index,
+                                content: text.clone(),
+                            })
+                            .await;
+                        delta_index += 1;
+                    }
+                }
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::ReasoningDelta { reasoning, .. },
+            )) => {
+                _accumulated_output_chars += reasoning.chars().count();
+                if let Some(sink) = &event_sink {
+                    sink.emit(AgentEvent::MessageThinkingDelta {
+                        index: delta_index,
+                        delta: reasoning.clone(),
+                    });
+                }
+                let _ = tx
+                    .send(RigStreamChunk::Thinking {
+                        index: delta_index,
+                        content: reasoning.clone(),
+                    })
+                    .await;
+                delta_index += 1;
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamAssistantItem(
+                rig::streaming::StreamedAssistantContent::ToolCall { tool_call, .. },
+            )) => {
+                let args = match &tool_call.function.arguments {
+                    serde_json::Value::String(s) => s.clone(),
+                    v => serde_json::to_string(v).unwrap_or_default(),
+                };
+                _accumulated_output_chars += args.chars().count();
+
+                let tool_name = tool_call.function.name.clone();
+                let tool_args: serde_json::Value =
+                    serde_json::from_str(&args).unwrap_or_default();
+
+                // Pre-tool-call guardrail hook
+                if let Ok(Some(decision)) = hooks.run_pre_tool_call(&tool_name, &tool_args).await {
+                    match decision {
+                        ToolGuardrailDecision::Allow => {}
+                        ToolGuardrailDecision::Block { reason } => {
+                            if let Some(sink) = &event_sink {
+                                sink.emit(AgentEvent::ToolExecutionEnd {
+                                    tool_call_id: tool_call.id.clone(),
+                                    tool_name: tool_name.clone(),
+                                    output: None,
+                                    error: Some(reason.clone()),
+                                    elapsed_ms: 0,
+                                });
+                            }
+                            let _ = tx
+                                .send(RigStreamChunk::ToolCallFinished {
+                                    tool_call_id: tool_call.id.clone(),
+                                    tool_name: tool_name.clone(),
+                                    output: format!("blocked: {reason}"),
+                                    error: Some(reason),
+                                })
+                                .await;
+                            tool_calls.push(ToolCallRecord {
+                                id: tool_call.id.clone(),
+                                name: tool_name,
+                                arguments: tool_args,
+                                output: None,
+                                error: Some("blocked by guardrail".to_string()),
+                                elapsed_ms: None,
+                            });
+                            continue;
+                        }
+                        ToolGuardrailDecision::RequireApproval { message } => {
+                            tool_calls.push(ToolCallRecord {
+                                id: tool_call.id.clone(),
+                                name: tool_name.clone(),
+                                arguments: tool_args,
+                                output: None,
+                                error: Some(format!("requires approval: {message}")),
+                                elapsed_ms: None,
+                            });
+                            continue;
+                        }
+                    }
+                }
+
+                if let Some(sink) = &event_sink {
+                    sink.emit(AgentEvent::ToolExecutionStart {
+                        tool_call_id: tool_call.id.clone(),
+                        tool_name: tool_name.clone(),
+                        arguments: tool_args.clone(),
+                    });
+                }
+
+                let _ = tx
+                    .send(RigStreamChunk::ToolCallStarted {
+                        tool_call_id: tool_call.id.clone(),
+                        tool_name: tool_name.clone(),
+                        arguments: args.clone(),
+                    })
+                    .await;
+                tool_calls.push(ToolCallRecord {
+                    id: tool_call.id.clone(),
+                    name: tool_name,
+                    arguments: tool_args,
+                    output: None,
+                    error: None,
+                    elapsed_ms: None,
+                });
+            }
+            Ok(rig::agent::MultiTurnStreamItem::StreamUserItem(
+                rig::streaming::StreamedUserContent::ToolResult { tool_result, .. },
+            )) => {
+                let content =
+                    super::helpers::tool_result_content_to_string(&tool_result.content);
+                _accumulated_output_chars += content.chars().count();
+
+                let tool_name = tool_calls
+                    .last()
+                    .map(|tc| tc.name.clone())
+                    .unwrap_or_default();
+
+                if let Some(last) = tool_calls.last_mut()
+                    && last.id == tool_result.id
+                {
+                    last.output = Some(serde_json::from_str(&content).unwrap_or_default());
+                }
+
+                if let Some(sink) = &event_sink {
+                    sink.emit(AgentEvent::ToolExecutionEnd {
+                        tool_call_id: tool_result.id.clone(),
+                        tool_name: tool_name.clone(),
+                        output: Some(serde_json::Value::String(content.clone())),
+                        error: None,
+                        elapsed_ms: 0,
+                    });
+                }
+
+                let _ = tx
+                    .send(RigStreamChunk::ToolCallFinished {
+                        tool_call_id: tool_result.id.clone(),
+                        tool_name,
+                        output: content.clone(),
+                        error: None,
+                    })
+                    .await;
+
+                if !hooks.is_empty() {
+                    let outcome = ToolCallOutcome {
+                        name: tool_result.id.clone(),
+                        arguments: serde_json::Value::Null,
+                        output: Some(serde_json::Value::String(content)),
+                        error: None,
+                        elapsed_ms: 0,
+                    };
+                    let _ = hooks.run_post_tool_call(&outcome).await;
+                }
+            }
+            Ok(rig::agent::MultiTurnStreamItem::FinalResponse(resp)) => {
+                let usage = resp.usage();
+                input_tokens = usage.input_tokens;
+                output_tokens = usage.output_tokens;
+
+                if !hooks.is_empty() {
+                    let hook_response = HookLlmResponse {
+                        content: Some(assistant_text.clone()),
+                        tool_calls: None,
+                        input_tokens,
+                        output_tokens,
+                        finish_reason: None,
+                    };
+                    let _ = hooks.run_post_llm_call(&hook_response).await;
+                }
+            }
+            Err(e) => {
+                warn!(error = %e, "turn stream error");
+                return Err(AiError::Api(format!("{e}")));
+            }
+            _ => {}
+        }
+    }
+
+    Ok(TurnOutput {
+        assistant_text,
+        tool_calls,
+        input_tokens,
+        output_tokens,
+    })
+}
+
+
diff --git a/lib/ai/agent/mod.rs b/lib/ai/agent/mod.rs
new file mode 100644
index 0000000..d5fa0b4
--- /dev/null
+++ b/lib/ai/agent/mod.rs
@@ -0,0 +1,98 @@
+pub mod agent;
+pub mod compression;
+pub mod config;
+pub mod error_classifier;
+pub mod events;
+pub mod helpers;
+pub mod hooks;
+pub mod iteration_budget;
+pub mod r#loop;
+pub mod persistence;
+pub mod prompt;
+pub mod prompt_builder;
+pub mod request;
+pub mod session;
+pub mod subagent;
+pub mod tool;
+
+use serde::{Deserialize, Serialize};
+
+pub use agent::RigAgent;
+pub use compression::{
+    CompactionResult, CompressionStrategy, build_branch_summary_prompt,
+    build_compression_prompt, build_compression_prompt_with_options,
+    estimate_truncation, plan_compaction,
+};
+pub use config::AgentConfig;
+pub use error_classifier::{
+    ErrorCategory, RetryPolicy, classify_error, retry_policy_for,
+    should_compact_before_retry, should_switch_to_fallback,
+};
+pub use events::{
+    AgentEvent, AgentEventMessage, EventSink, EventToolCall, MessageRole,
+};
+pub use hooks::{AgentHook, HookChain, ToolCallOutcome, ToolGuardrailDecision};
+pub use iteration_budget::IterationBudget;
+pub use r#loop::{
+    AgentLoopConfig, EnhancedAgent, PrepareNextTurnFn, ShouldStopFn,
+    ToolExecutionMode, TurnContext, TurnUpdate,
+};
+pub use persistence::{
+    AgentRealtime, AgentRunContext, AgentRuntime, AgentStreamEvent,
+};
+pub use prompt_builder::SystemPromptBuilder;
+pub use request::{
+    AgentContextChunk, AgentExpert, AgentExpertOutput, AgentMessage,
+    AgentRequest, AgentResult, AgentStep, ToolCallRecord,
+};
+pub use session::{
+    CompactionOptions, Session, SessionEntry, SessionHeader,
+    SessionMessageRole, SessionToolCall, SessionToolResult,
+};
+pub use tool::{RigTool, RigToolSet};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum RigStreamChunk {
+    TextDelta {
+        index: usize,
+        content: String,
+    },
+    Thinking {
+        index: usize,
+        content: String,
+    },
+    ToolCallStarted {
+        tool_call_id: String,
+        tool_name: String,
+        arguments: String,
+    },
+    ToolCallFinished {
+        tool_call_id: String,
+        tool_name: String,
+        output: String,
+        error: Option<String>,
+    },
+    SubagentStarted {
+        subagent_id: String,
+        role: String,
+        task: String,
+    },
+    SubagentCompleted {
+        subagent_id: String,
+        role: String,
+        task: String,
+        output: String,
+    },
+    SubagentFailed {
+        error: String,
+    },
+    Final {
+        content: String,
+        input_tokens: u64,
+        output_tokens: u64,
+    },
+    Failed {
+        error: String,
+    },
+}
diff --git a/lib/ai/agent/persistence/db.rs b/lib/ai/agent/persistence/db.rs
new file mode 100644
index 0000000..5e0bdd5
--- /dev/null
+++ b/lib/ai/agent/persistence/db.rs
@@ -0,0 +1,33 @@
+use std::time::Instant;
+
+use crate::agent::persistence::types::{ActiveAgentRun, AgentRunContext};
+use crate::error::AiResult;
+
+impl super::types::AgentRuntime {
+    pub async fn start_run(
+        &self,
+        run_context: Option<&AgentRunContext>,
+    ) -> AiResult<ActiveAgentRun> {
+        let Some(run_context) = run_context else {
+            return Ok(ActiveAgentRun {
+                conversation_id: None,
+                message_id: None,
+                invocation_id: None,
+                session_id: None,
+                user_id: None,
+                started_at: Instant::now(),
+                current_step: 0,
+            });
+        };
+
+        Ok(ActiveAgentRun {
+            conversation_id: run_context.conversation_id,
+            message_id: None,
+            invocation_id: run_context.invocation_id,
+            session_id: run_context.session_id,
+            user_id: run_context.user_id,
+            started_at: Instant::now(),
+            current_step: 0,
+        })
+    }
+}
diff --git a/lib/ai/agent/persistence/mod.rs b/lib/ai/agent/persistence/mod.rs
new file mode 100644
index 0000000..84a682c
--- /dev/null
+++ b/lib/ai/agent/persistence/mod.rs
@@ -0,0 +1,8 @@
+pub mod db;
+pub mod realtime;
+pub mod types;
+
+pub use types::{
+    ActiveAgentRun, AgentRealtime, AgentRunContext, AgentRuntime,
+    AgentStreamEvent, estimate_output_tokens,
+};
diff --git a/lib/ai/agent/persistence/realtime.rs b/lib/ai/agent/persistence/realtime.rs
new file mode 100644
index 0000000..6254ce3
--- /dev/null
+++ b/lib/ai/agent/persistence/realtime.rs
@@ -0,0 +1,38 @@
+use crate::agent::persistence::types::{
+    AgentRealtime, AgentRuntime, AgentStreamEvent,
+};
+use crate::error::AiResult;
+
+pub async fn publish_event(
+    runtime: &AgentRuntime,
+    _realtime: Option<&AgentRealtime>,
+    event: &AgentStreamEvent,
+) -> AiResult<()> {
+    let Some(tx) = &runtime.tx else {
+        return Ok(());
+    };
+
+    let payload = match serde_json::to_string(event) {
+        Ok(p) => p,
+        Err(error) => {
+            tracing::warn!(error = %error, "agent sse: serialize failed");
+            return Ok(());
+        }
+    };
+
+    if tx.send(payload).is_err() {
+        tracing::debug!("agent sse: mpsc send failed, client disconnected");
+    }
+
+    Ok(())
+}
+
+impl AgentRuntime {
+    pub async fn publish(
+        &self,
+        realtime: Option<&AgentRealtime>,
+        event: &AgentStreamEvent,
+    ) -> AiResult<()> {
+        publish_event(self, realtime, event).await
+    }
+}
diff --git a/lib/ai/agent/persistence/types.rs b/lib/ai/agent/persistence/types.rs
new file mode 100644
index 0000000..5b621d8
--- /dev/null
+++ b/lib/ai/agent/persistence/types.rs
@@ -0,0 +1,177 @@
+use std::time::Instant;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use tokio::sync::mpsc;
+use uuid::Uuid;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentRealtime {
+    pub channel: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentRunContext {
+    pub conversation_id: Option<Uuid>,
+    pub invocation_id: Option<Uuid>,
+    pub session_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub realtime: Option<AgentRealtime>,
+}
+
+impl AgentRunContext {
+    pub fn new(user_id: Uuid) -> Self {
+        Self {
+            conversation_id: None,
+            invocation_id: None,
+            session_id: None,
+            user_id: Some(user_id),
+            realtime: None,
+        }
+    }
+
+    pub fn with_conversation_id(mut self, id: Uuid) -> Self {
+        self.conversation_id = Some(id);
+        self
+    }
+
+    pub fn with_invocation_id(mut self, id: Uuid) -> Self {
+        self.invocation_id = Some(id);
+        self
+    }
+
+    pub fn with_session_id(mut self, id: Uuid) -> Self {
+        self.session_id = Some(id);
+        self
+    }
+
+    pub fn with_realtime(mut self, realtime: AgentRealtime) -> Self {
+        self.realtime = Some(realtime);
+        self
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum AgentStreamEvent {
+    Started {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        session_id: Option<Uuid>,
+        model: String,
+    },
+    Delta {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        index: usize,
+        content: String,
+    },
+    Thinking {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        index: usize,
+        content: String,
+    },
+    ToolCallStarted {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        session_id: Option<Uuid>,
+        tool_call_id: String,
+        tool_name: String,
+        arguments: Value,
+    },
+    ToolCallFinished {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        session_id: Option<Uuid>,
+        tool_call_id: String,
+        tool_name: String,
+        output: Option<Value>,
+        error: Option<String>,
+        execution_time_ms: i64,
+    },
+    SubagentStarted {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        subagent_id: String,
+        role: String,
+        task: String,
+        model: String,
+    },
+    SubagentDelta {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        subagent_id: String,
+        index: usize,
+        content: String,
+    },
+    SubagentCompleted {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        subagent_id: String,
+        role: String,
+        task: String,
+        output: String,
+        input_tokens: i64,
+        output_tokens: i64,
+        model: String,
+    },
+    SubagentFailed {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        subagent_id: String,
+        error: String,
+    },
+    Completed {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        session_id: Option<Uuid>,
+        output: String,
+        input_tokens: i64,
+        output_tokens: i64,
+        latency_ms: i32,
+        stop_reason: Option<String>,
+    },
+    Failed {
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        session_id: Option<Uuid>,
+        error: String,
+    },
+}
+
+#[derive(Clone)]
+pub struct AgentRuntime {
+    pub tx: Option<mpsc::UnboundedSender<String>>,
+}
+
+impl AgentRuntime {
+    pub fn new(tx: mpsc::UnboundedSender<String>) -> Self {
+        Self { tx: Some(tx) }
+    }
+
+    pub fn empty() -> Self {
+        Self { tx: None }
+    }
+}
+
+impl Default for AgentRuntime {
+    fn default() -> Self {
+        Self::empty()
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct ActiveAgentRun {
+    pub conversation_id: Option<Uuid>,
+    pub message_id: Option<Uuid>,
+    pub invocation_id: Option<Uuid>,
+    pub session_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub started_at: Instant,
+    pub current_step: usize,
+}
+
+pub fn estimate_output_tokens(output: &str) -> i64 {
+    (output.chars().count() as f64 / 4.0).ceil() as i64
+}
diff --git a/lib/ai/agent/prompt.rs b/lib/ai/agent/prompt.rs
new file mode 100644
index 0000000..9e18379
--- /dev/null
+++ b/lib/ai/agent/prompt.rs
@@ -0,0 +1,57 @@
+use rig::agent::AgentBuilder;
+use rig::client::CompletionClient;
+use rig::completion::Prompt;
+
+use super::agent::RigAgent;
+use super::helpers::with_retry;
+use crate::error::{AiError, AiResult};
+
+impl RigAgent {
+    pub async fn prompt(
+        &self,
+        system_prompt: &str,
+        user_input: &str,
+    ) -> AiResult<(String, u64, u64)> {
+        let model_name = self.config.model.clone();
+        let client = self.client.llm_client().clone();
+        let temperature = self.config.temperature;
+        let max_completion_tokens = self.config.max_completion_tokens;
+        let retry_attempts = self.config.retry_max_attempts;
+        let retry_delay_ms = self.config.retry_base_delay_ms;
+        let sp = system_prompt.to_string();
+        let ui = user_input.to_string();
+
+        with_retry(retry_attempts, retry_delay_ms, || {
+            let client = client.clone();
+            let model_name = model_name.clone();
+            let sp = sp.clone();
+            let ui = ui.clone();
+            async move {
+                let model = client.completion_model(&model_name);
+                let mut builder = AgentBuilder::new(model).preamble(&sp);
+                if let Some(temp) = temperature {
+                    builder = builder.temperature(temp);
+                }
+                if let Some(mt) = max_completion_tokens {
+                    builder = builder.max_tokens(mt);
+                }
+                let agent = builder.build();
+
+                let response = agent
+                    .prompt(&ui)
+                    .extended_details()
+                    .await
+                    .map_err(|e: rig::completion::PromptError| {
+                        AiError::Api(e.to_string())
+                    })?;
+
+                Ok((
+                    response.output,
+                    response.usage.input_tokens,
+                    response.usage.output_tokens,
+                ))
+            }
+        })
+        .await
+    }
+}
diff --git a/lib/ai/agent/prompt_builder.rs b/lib/ai/agent/prompt_builder.rs
new file mode 100644
index 0000000..fc4a1ba
--- /dev/null
+++ b/lib/ai/agent/prompt_builder.rs
@@ -0,0 +1,251 @@
+use std::collections::HashMap;
+
+/// Modular system prompt builder inspired by pi's `buildSystemPrompt`.
+///
+/// Supports:
+/// - Base prompt (replaceable or appendable)
+/// - Tool snippets injected into an "Available tools" section
+/// - Project context files (AGENTS.md, etc.)
+/// - Skills injection
+/// - Variable substitution ({{key}})
+/// - Metadata (date)
+///
+/// # Example
+/// ```rust
+/// use ai::agent::prompt_builder::SystemPromptBuilder;
+///
+/// let prompt = SystemPromptBuilder::new()
+///     .base_prompt("You are a helpful assistant.")
+///     .tool_snippet("bash", "Execute shell commands")
+///     .tool_snippet("read", "Read file contents")
+///     .project_context("AGENTS.md", "# Project Rules\n- Follow conventions")
+///     .variable("repo_name", "gitdataai")
+///     .build();
+/// ```
+#[derive(Clone, Debug)]
+pub struct SystemPromptBuilder {
+    base_prompt: Option<String>,
+    append_prompt: Option<String>,
+    tool_snippets: Vec<(String, String)>,
+    tool_guidelines: Vec<String>,
+    project_contexts: Vec<(String, String)>,
+    skills: Vec<String>,
+    variables: HashMap<String, String>,
+    date: Option<String>,
+    custom_sections: Vec<(String, String)>,
+}
+
+impl SystemPromptBuilder {
+    pub fn new() -> Self {
+        Self {
+            base_prompt: None,
+            append_prompt: None,
+            tool_snippets: Vec::new(),
+            tool_guidelines: Vec::new(),
+            project_contexts: Vec::new(),
+            skills: Vec::new(),
+            variables: HashMap::new(),
+            date: None,
+            custom_sections: Vec::new(),
+        }
+    }
+
+    /// Set the base system prompt. Replaces the default prompt.
+    pub fn base_prompt(mut self, prompt: impl Into<String>) -> Self {
+        self.base_prompt = Some(prompt.into());
+        self
+    }
+
+    /// Append additional text to the system prompt after the base.
+    pub fn append_prompt(mut self, text: impl Into<String>) -> Self {
+        self.append_prompt = Some(text.into());
+        self
+    }
+
+    /// Add a one-line tool description snippet.
+    pub fn tool_snippet(mut self, tool_name: impl Into<String>, description: impl Into<String>) -> Self {
+        self.tool_snippets.push((tool_name.into(), description.into()));
+        self
+    }
+
+    /// Add a guideline bullet for the tools section.
+    pub fn tool_guideline(mut self, guideline: impl Into<String>) -> Self {
+        self.tool_guidelines.push(guideline.into());
+        self
+    }
+
+    /// Add a project context file (e.g., AGENTS.md content).
+    pub fn project_context(mut self, path: impl Into<String>, content: impl Into<String>) -> Self {
+        self.project_contexts.push((path.into(), content.into()));
+        self
+    }
+
+    /// Add a skill description to inject into the prompt.
+    pub fn skill(mut self, skill_description: impl Into<String>) -> Self {
+        self.skills.push(skill_description.into());
+        self
+    }
+
+    /// Set a variable for {{key}} substitution.
+    pub fn variable(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
+        self.variables.insert(key.into(), value.into());
+        self
+    }
+
+    /// Set multiple variables from an iterator.
+    pub fn variables(mut self, vars: impl IntoIterator<Item = (String, String)>) -> Self {
+        self.variables.extend(vars);
+        self
+    }
+
+    /// Set the date metadata (ISO format: YYYY-MM-DD).
+    pub fn date(mut self, date: impl Into<String>) -> Self {
+        self.date = Some(date.into());
+        self
+    }
+
+    /// Add a custom named section to the prompt.
+    pub fn custom_section(mut self, name: impl Into<String>, content: impl Into<String>) -> Self {
+        self.custom_sections.push((name.into(), content.into()));
+        self
+    }
+
+    /// Build the final system prompt string.
+    pub fn build(self) -> String {
+        let mut parts: Vec<String> = Vec::new();
+
+        // 1. Base prompt
+        if let Some(base) = &self.base_prompt {
+            parts.push(base.clone());
+        }
+
+        // 2. Append prompt
+        if let Some(append) = &self.append_prompt {
+            parts.push(append.clone());
+        }
+
+        // 3. Tool snippets section
+        if !self.tool_snippets.is_empty() {
+            let mut section = String::from("\n## Available Tools\n");
+            for (name, desc) in &self.tool_snippets {
+                section.push_str(&format!("- `{name}`: {desc}\n"));
+            }
+            if !self.tool_guidelines.is_empty() {
+                section.push_str("\n### Tool Guidelines\n");
+                for guideline in &self.tool_guidelines {
+                    section.push_str(&format!("- {guideline}\n"));
+                }
+            }
+            parts.push(section);
+        }
+
+        // 4. Project context files
+        if !self.project_contexts.is_empty() {
+            let mut section = String::from("\n<project_context>\n\n");
+            section.push_str("Project-specific instructions and guidelines:\n\n");
+            for (path, content) in &self.project_contexts {
+                section.push_str(&format!("<project_instructions path=\"{path}\">\n{content}\n</project_instructions>\n\n"));
+            }
+            section.push_str("</project_context>");
+            parts.push(section);
+        }
+
+        // 5. Skills section
+        if !self.skills.is_empty() {
+            let mut section = String::from("\n## Available Skills\n");
+            for skill in &self.skills {
+                section.push_str(&format!("{skill}\n"));
+            }
+            parts.push(section);
+        }
+
+        // 6. Custom sections
+        for (name, content) in &self.custom_sections {
+            parts.push(format!("\n## {name}\n{content}"));
+        }
+
+        // 7. Metadata footer
+        if let Some(date) = &self.date {
+            parts.push(format!("\nCurrent date: {date}"));
+        }
+
+        let mut result = parts.join("\n");
+
+        // 8. Variable substitution
+        for (key, value) in &self.variables {
+            let placeholder = format!("{{{{{}}}}}", key);
+            result = result.replace(&placeholder, value);
+        }
+
+        result
+    }
+}
+
+impl Default for SystemPromptBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_basic_build() {
+        let prompt = SystemPromptBuilder::new()
+            .base_prompt("You are a helpful assistant.")
+            .date("2026-05-29")
+            .build();
+
+        assert!(prompt.contains("You are a helpful assistant."));
+        assert!(prompt.contains("Current date: 2026-05-29"));
+    }
+
+    #[test]
+    fn test_variable_substitution() {
+        let prompt = SystemPromptBuilder::new()
+            .base_prompt("Repo: {{repo_name}}, User: {{user}}")
+            .variable("repo_name", "gitdataai")
+            .variable("user", "zhenyi")
+            .build();
+
+        assert!(prompt.contains("Repo: gitdataai"));
+        assert!(prompt.contains("User: zhenyi"));
+    }
+
+    #[test]
+    fn test_tool_snippets() {
+        let prompt = SystemPromptBuilder::new()
+            .base_prompt("Agent prompt.")
+            .tool_snippet("bash", "Execute shell commands")
+            .tool_snippet("read", "Read file contents")
+            .build();
+
+        assert!(prompt.contains("## Available Tools"));
+        assert!(prompt.contains("`bash`: Execute shell commands"));
+    }
+
+    #[test]
+    fn test_project_context() {
+        let prompt = SystemPromptBuilder::new()
+            .base_prompt("Base.")
+            .project_context("AGENTS.md", "# Rules\n- Follow conventions")
+            .build();
+
+        assert!(prompt.contains("<project_context>"));
+        assert!(prompt.contains("AGENTS.md"));
+        assert!(prompt.contains("Follow conventions"));
+    }
+
+    #[test]
+    fn test_custom_section() {
+        let prompt = SystemPromptBuilder::new()
+            .base_prompt("Base.")
+            .custom_section("Memory", "Remember: user prefers Rust")
+            .build();
+
+        assert!(prompt.contains("## Memory"));
+        assert!(prompt.contains("user prefers Rust"));
+    }
+}
diff --git a/lib/ai/agent/request.rs b/lib/ai/agent/request.rs
new file mode 100644
index 0000000..e9ed174
--- /dev/null
+++ b/lib/ai/agent/request.rs
@@ -0,0 +1,240 @@
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use tokio_util::sync::CancellationToken;
+
+use super::persistence::AgentRunContext;
+use crate::error::{AiError, AiResult};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentRequest {
+    pub input: String,
+    pub messages: Vec<AgentMessage>,
+    pub context: Vec<AgentContextChunk>,
+    pub experts: Vec<AgentExpert>,
+    pub run_context: Option<AgentRunContext>,
+    #[serde(skip)]
+    pub prefill_messages: Vec<rig::completion::Message>,
+    #[serde(skip)]
+    pub cancellation_token: Option<CancellationToken>,
+    #[serde(skip)]
+    pub timeout: Option<Duration>,
+}
+
+impl AgentRequest {
+    pub fn new(input: impl Into<String>) -> Self {
+        Self {
+            input: input.into(),
+            messages: Vec::new(),
+            context: Vec::new(),
+            experts: Vec::new(),
+            run_context: None,
+            prefill_messages: Vec::new(),
+            cancellation_token: None,
+            timeout: None,
+        }
+    }
+
+    pub fn validate(&self) -> AiResult<()> {
+        if self.input.trim().is_empty() {
+            return Err(AiError::Config("agent request input is required".to_string()));
+        }
+        if self.input.len() > 1_000_000 {
+            return Err(AiError::Config(
+                "agent request input exceeds maximum length (1MB)".to_string(),
+            ));
+        }
+        if self.experts.len() > 32 {
+            return Err(AiError::Config(
+                "agent request experts count exceeds maximum (32)".to_string(),
+            ));
+        }
+        Ok(())
+    }
+
+    pub fn with_messages(mut self, messages: Vec<AgentMessage>) -> Self {
+        self.messages = messages;
+        self
+    }
+
+    pub fn with_context(mut self, context: Vec<AgentContextChunk>) -> Self {
+        self.context = context;
+        self
+    }
+
+    pub fn add_context(mut self, chunk: AgentContextChunk) -> Self {
+        self.context.push(chunk);
+        self
+    }
+
+    pub fn with_experts(mut self, experts: Vec<AgentExpert>) -> Self {
+        self.experts = experts;
+        self
+    }
+
+    pub fn add_expert(mut self, expert: AgentExpert) -> Self {
+        self.experts.push(expert);
+        self
+    }
+
+    pub fn with_run_context(mut self, run_context: AgentRunContext) -> Self {
+        self.run_context = Some(run_context);
+        self
+    }
+
+    pub fn with_prefill_messages(mut self, prefill_messages: Vec<rig::completion::Message>) -> Self {
+        self.prefill_messages = prefill_messages;
+        self
+    }
+
+    pub fn with_cancellation_token(mut self, cancellation_token: CancellationToken) -> Self {
+        self.cancellation_token = Some(cancellation_token);
+        self
+    }
+
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = Some(timeout);
+        self
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum AgentMessage {
+    User(String),
+    Assistant(String),
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentExpert {
+    pub id: String,
+    pub role: String,
+    pub task: String,
+    pub system_prompt: Option<String>,
+    pub context: Vec<AgentContextChunk>,
+    /// Override the master agent's temperature for this subagent.
+    pub temperature: Option<f64>,
+    /// Override the master agent's max_completion_tokens for this subagent.
+    pub max_completion_tokens: Option<u64>,
+}
+
+impl AgentExpert {
+    pub fn new(id: impl Into<String>, role: impl Into<String>, task: impl Into<String>) -> Self {
+        Self {
+            id: id.into(),
+            role: role.into(),
+            task: task.into(),
+            system_prompt: None,
+            context: Vec::new(),
+            temperature: None,
+            max_completion_tokens: None,
+        }
+    }
+
+    pub fn with_system_prompt(mut self, system_prompt: impl Into<String>) -> Self {
+        self.system_prompt = Some(system_prompt.into());
+        self
+    }
+
+    pub fn with_context(mut self, context: Vec<AgentContextChunk>) -> Self {
+        self.context = context;
+        self
+    }
+
+    pub fn with_temperature(mut self, temperature: f64) -> Self {
+        self.temperature = Some(temperature);
+        self
+    }
+
+    pub fn with_max_completion_tokens(mut self, max_tokens: u64) -> Self {
+        self.max_completion_tokens = Some(max_tokens);
+        self
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentContextChunk {
+    pub id: String,
+    pub content: String,
+    pub source: Option<String>,
+    pub score: Option<f32>,
+    pub metadata: Value,
+}
+
+impl AgentContextChunk {
+    pub fn new(id: impl Into<String>, content: impl Into<String>) -> Self {
+        Self {
+            id: id.into(),
+            content: content.into(),
+            source: None,
+            score: None,
+            metadata: Value::Null,
+        }
+    }
+}
+
+impl From<crate::rag::RagSearchHit> for AgentContextChunk {
+    fn from(hit: crate::rag::RagSearchHit) -> Self {
+        Self {
+            id: hit.id,
+            content: hit.content,
+            source: Some(hit.session_id),
+            score: Some(hit.score),
+            metadata: Value::Object(hit.metadata.into_iter().collect()),
+        }
+    }
+}
+
+impl From<&AgentExpertOutput> for AgentContextChunk {
+    fn from(output: &AgentExpertOutput) -> Self {
+        Self {
+            id: format!("subagent:{}", output.id),
+            content: output.output.clone(),
+            source: Some(output.role.clone()),
+            score: None,
+            metadata: serde_json::json!({
+                "kind": "subagent",
+                "task": output.task,
+            }),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentResult {
+    pub output: String,
+    pub steps: Vec<AgentStep>,
+    pub expert_outputs: Vec<AgentExpertOutput>,
+    pub input_tokens: i64,
+    pub output_tokens: i64,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentStep {
+    pub index: usize,
+    pub assistant: Option<String>,
+    pub reasoning_content: Option<String>,
+    pub tool_calls: Vec<ToolCallRecord>,
+    pub reflection: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ToolCallRecord {
+    pub id: String,
+    pub name: String,
+    pub arguments: Value,
+    pub output: Option<Value>,
+    pub error: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub elapsed_ms: Option<i64>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentExpertOutput {
+    pub id: String,
+    pub role: String,
+    pub task: String,
+    pub output: String,
+    pub input_tokens: i64,
+    pub output_tokens: i64,
+}
diff --git a/lib/ai/agent/session.rs b/lib/ai/agent/session.rs
new file mode 100644
index 0000000..972a980
--- /dev/null
+++ b/lib/ai/agent/session.rs
@@ -0,0 +1,535 @@
+use std::time::SystemTime;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::error::{AiError, AiResult};
+
+/// Current session file format version.
+pub const SESSION_VERSION: u32 = 2;
+
+/// Session metadata header.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SessionHeader {
+    pub version: u32,
+    pub id: Uuid,
+    pub created_at: String,
+    pub parent_session: Option<Uuid>,
+    pub name: Option<String>,
+}
+
+impl SessionHeader {
+    pub fn new() -> Self {
+        Self {
+            version: SESSION_VERSION,
+            id: Uuid::new_v4(),
+            created_at: iso_now(),
+            parent_session: None,
+            name: None,
+        }
+    }
+
+    pub fn with_parent(mut self, parent: Uuid) -> Self {
+        self.parent_session = Some(parent);
+        self
+    }
+
+    pub fn with_name(mut self, name: impl Into<String>) -> Self {
+        self.name = Some(name.into());
+        self
+    }
+}
+
+/// Typed session entry — each entry in a session transcript is one of these variants.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum SessionEntry {
+    /// A user or assistant message.
+    Message {
+        id: Uuid,
+        parent_id: Option<Uuid>,
+        timestamp: String,
+        role: SessionMessageRole,
+        content: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        tool_calls: Option<Vec<SessionToolCall>>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        tool_result: Option<SessionToolResult>,
+    },
+
+    /// A context compaction event (older messages summarized).
+    Compaction {
+        id: Uuid,
+        parent_id: Option<Uuid>,
+        timestamp: String,
+        summary: String,
+        first_kept_entry_id: Uuid,
+        messages_compacted: usize,
+        tokens_saved: i64,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        details: Option<Value>,
+    },
+
+    /// A branch summary (created when forking from a different point in the tree).
+    BranchSummary {
+        id: Uuid,
+        parent_id: Option<Uuid>,
+        timestamp: String,
+        from_entry_id: Uuid,
+        summary: String,
+        entries_summarized: usize,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        label: Option<String>,
+    },
+
+    /// Model change during a session.
+    ModelChange {
+        id: Uuid,
+        parent_id: Option<Uuid>,
+        timestamp: String,
+        provider: String,
+        model_id: String,
+    },
+
+    /// Thinking level change during a session.
+    ThinkingLevelChange {
+        id: Uuid,
+        parent_id: Option<Uuid>,
+        timestamp: String,
+        level: String,
+    },
+
+    /// Custom extension data (not sent to LLM).
+    Custom {
+        id: Uuid,
+        parent_id: Option<Uuid>,
+        timestamp: String,
+        custom_type: String,
+        data: Option<Value>,
+    },
+}
+
+impl SessionEntry {
+    pub fn id(&self) -> Uuid {
+        match self {
+            Self::Message { id, .. }
+            | Self::Compaction { id, .. }
+            | Self::BranchSummary { id, .. }
+            | Self::ModelChange { id, .. }
+            | Self::ThinkingLevelChange { id, .. }
+            | Self::Custom { id, .. } => *id,
+        }
+    }
+
+    pub fn parent_id(&self) -> Option<Uuid> {
+        match self {
+            Self::Message { parent_id, .. }
+            | Self::Compaction { parent_id, .. }
+            | Self::BranchSummary { parent_id, .. }
+            | Self::ModelChange { parent_id, .. }
+            | Self::ThinkingLevelChange { parent_id, .. }
+            | Self::Custom { parent_id, .. } => *parent_id,
+        }
+    }
+
+    pub fn timestamp(&self) -> &str {
+        match self {
+            Self::Message { timestamp, .. }
+            | Self::Compaction { timestamp, .. }
+            | Self::BranchSummary { timestamp, .. }
+            | Self::ModelChange { timestamp, .. }
+            | Self::ThinkingLevelChange { timestamp, .. }
+            | Self::Custom { timestamp, .. } => timestamp,
+        }
+    }
+
+    /// Create a user message entry.
+    pub fn user_message(parent_id: Option<Uuid>, content: impl Into<String>) -> Self {
+        Self::Message {
+            id: Uuid::new_v4(),
+            parent_id,
+            timestamp: iso_now(),
+            role: SessionMessageRole::User,
+            content: content.into(),
+            tool_calls: None,
+            tool_result: None,
+        }
+    }
+
+    /// Create an assistant message entry.
+    pub fn assistant_message(
+        parent_id: Option<Uuid>,
+        content: impl Into<String>,
+        tool_calls: Option<Vec<SessionToolCall>>,
+    ) -> Self {
+        Self::Message {
+            id: Uuid::new_v4(),
+            parent_id,
+            timestamp: iso_now(),
+            role: SessionMessageRole::Assistant,
+            content: content.into(),
+            tool_calls,
+            tool_result: None,
+        }
+    }
+
+    /// Create a compaction entry.
+    pub fn compaction(
+        parent_id: Option<Uuid>,
+        summary: impl Into<String>,
+        first_kept_entry_id: Uuid,
+        messages_compacted: usize,
+        tokens_saved: i64,
+    ) -> Self {
+        Self::Compaction {
+            id: Uuid::new_v4(),
+            parent_id,
+            timestamp: iso_now(),
+            summary: summary.into(),
+            first_kept_entry_id,
+            messages_compacted,
+            tokens_saved,
+            details: None,
+        }
+    }
+
+    /// Create a branch summary entry.
+    pub fn branch_summary(
+        parent_id: Option<Uuid>,
+        from_entry_id: Uuid,
+        summary: impl Into<String>,
+        entries_summarized: usize,
+        label: Option<String>,
+    ) -> Self {
+        Self::BranchSummary {
+            id: Uuid::new_v4(),
+            parent_id,
+            timestamp: iso_now(),
+            from_entry_id,
+            summary: summary.into(),
+            entries_summarized,
+            label,
+        }
+    }
+
+    /// Create a model change entry.
+    pub fn model_change(
+        parent_id: Option<Uuid>,
+        provider: impl Into<String>,
+        model_id: impl Into<String>,
+    ) -> Self {
+        Self::ModelChange {
+            id: Uuid::new_v4(),
+            parent_id,
+            timestamp: iso_now(),
+            provider: provider.into(),
+            model_id: model_id.into(),
+        }
+    }
+
+    /// Create a custom extension entry.
+    pub fn custom(
+        parent_id: Option<Uuid>,
+        custom_type: impl Into<String>,
+        data: Option<Value>,
+    ) -> Self {
+        Self::Custom {
+            id: Uuid::new_v4(),
+            parent_id,
+            timestamp: iso_now(),
+            custom_type: custom_type.into(),
+            data,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum SessionMessageRole {
+    User,
+    Assistant,
+    ToolResult,
+    System,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SessionToolCall {
+    pub id: String,
+    pub name: String,
+    pub arguments: Value,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SessionToolResult {
+    pub tool_call_id: String,
+    pub tool_name: String,
+    pub content: String,
+    pub is_error: bool,
+}
+
+/// A full session: header + ordered list of entries forming a tree.
+///
+/// The tree structure supports forking: entries share `parent_id` links,
+/// and the "active branch" is determined by following from the leaf
+/// back to the root.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Session {
+    pub header: SessionHeader,
+    pub entries: Vec<SessionEntry>,
+}
+
+impl Session {
+    pub fn new() -> Self {
+        Self {
+            header: SessionHeader::new(),
+            entries: Vec::new(),
+        }
+    }
+
+    pub fn with_name(mut self, name: impl Into<String>) -> Self {
+        self.header = self.header.with_name(name);
+        self
+    }
+
+    /// Append an entry to the session.
+    pub fn push(&mut self, entry: SessionEntry) {
+        self.entries.push(entry);
+    }
+
+    /// Get the last entry's id (used as parent_id for the next entry).
+    pub fn last_entry_id(&self) -> Option<Uuid> {
+        self.entries.last().map(|e| e.id())
+    }
+
+    /// Get all entries on the active branch (from root to leaf).
+    pub fn active_branch(&self) -> Vec<&SessionEntry> {
+        if self.entries.is_empty() {
+            return Vec::new();
+        }
+
+        let mut branch = Vec::new();
+        let mut current_id = Some(self.entries.last().unwrap().id());
+
+        while let Some(id) = current_id {
+            if let Some(entry) = self.entries.iter().find(|e| e.id() == id) {
+                branch.push(entry);
+                current_id = entry.parent_id();
+            } else {
+                break;
+            }
+        }
+
+        branch.reverse();
+        branch
+    }
+
+    /// Get all message entries on the active branch (for LLM context).
+    pub fn active_messages(&self) -> Vec<&SessionEntry> {
+        self.active_branch()
+            .into_iter()
+            .filter(|e| matches!(e, SessionEntry::Message { .. } | SessionEntry::Compaction { .. }))
+            .collect()
+    }
+
+    /// Find all children of a given entry (for tree navigation).
+    pub fn children_of(&self, parent_id: Uuid) -> Vec<&SessionEntry> {
+        self.entries
+            .iter()
+            .filter(|e| e.parent_id() == Some(parent_id))
+            .collect()
+    }
+
+    /// Get all leaf entries (entries with no children).
+    pub fn leaves(&self) -> Vec<&SessionEntry> {
+        let parent_ids: std::collections::HashSet<Uuid> = self
+            .entries
+            .iter()
+            .filter_map(|e| e.parent_id())
+            .collect();
+
+        self.entries
+            .iter()
+            .filter(|e| !parent_ids.contains(&e.id()))
+            .collect()
+    }
+
+    /// Count total entries.
+    pub fn entry_count(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Fork from a specific entry, creating entries that belong to a new branch.
+    /// Returns the entries that should be in the new branch (from root to fork point).
+    pub fn fork_from(&self, fork_entry_id: Uuid) -> AiResult<Session> {
+        let fork_idx = self
+            .entries
+            .iter()
+            .position(|e| e.id() == fork_entry_id)
+            .ok_or_else(|| {
+                AiError::Config(format!("fork entry {fork_entry_id} not found in session"))
+            })?;
+
+        let mut new_session = Session::new();
+        new_session.header = new_session.header.with_parent(self.header.id);
+
+        // Copy entries up to and including the fork point
+        for entry in &self.entries[..=fork_idx] {
+            new_session.entries.push(entry.clone());
+        }
+
+        Ok(new_session)
+    }
+
+    /// Find the common ancestor of two entries.
+    pub fn common_ancestor(&self, id_a: Uuid, id_b: Uuid) -> Option<Uuid> {
+        let ancestors_a = self.ancestor_chain(id_a);
+        let ancestors_b: std::collections::HashSet<Uuid> =
+            self.ancestor_chain(id_b).into_iter().collect();
+
+        for ancestor in ancestors_a {
+            if ancestors_b.contains(&ancestor) {
+                return Some(ancestor);
+            }
+        }
+        None
+    }
+
+    /// Get the chain of ancestor IDs from an entry back to the root.
+    fn ancestor_chain(&self, entry_id: Uuid) -> Vec<Uuid> {
+        let mut chain = Vec::new();
+        let mut current_id = Some(entry_id);
+
+        while let Some(id) = current_id {
+            chain.push(id);
+            current_id = self
+                .entries
+                .iter()
+                .find(|e| e.id() == id)
+                .and_then(|e| e.parent_id());
+        }
+
+        chain
+    }
+}
+
+/// Options for session compaction.
+#[derive(Debug, Clone)]
+pub struct CompactionOptions {
+    /// Custom instructions for the compaction LLM call.
+    pub custom_instructions: Option<String>,
+    /// Reserve this many tokens for the prompt + LLM response.
+    pub reserve_tokens: i64,
+    /// Keep this many recent message pairs untouched.
+    pub keep_recent_pairs: usize,
+    /// Whether to generate branch summaries for forked branches.
+    pub branch_summarization: bool,
+}
+
+impl Default for CompactionOptions {
+    fn default() -> Self {
+        Self {
+            custom_instructions: None,
+            reserve_tokens: 16_384,
+            keep_recent_pairs: 4,
+            branch_summarization: true,
+        }
+    }
+}
+
+fn iso_now() -> String {
+    SystemTime::now()
+        .duration_since(SystemTime::UNIX_EPOCH)
+        .map(|d| {
+            let secs = d.as_secs();
+            // Simple ISO 8601 format (UTC)
+            let days = secs / 86400;
+            let years = (days * 400) / 146097;
+            let remaining_days = days - (years * 365 + years / 4 - years / 100 + years / 400);
+            let month_days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+            let is_leap = (years % 4 == 0 && years % 100 != 0) || years % 400 == 0;
+            let mut month = 0usize;
+            let mut day_acc = remaining_days as i64;
+            for (i, &md) in month_days.iter().enumerate() {
+                let md = if i == 1 && is_leap { md + 1 } else { md };
+                if day_acc < md as i64 {
+                    month = i;
+                    break;
+                }
+                day_acc -= md as i64;
+            }
+            let day = day_acc + 1;
+            let hour = (secs % 86400) / 3600;
+            let minute = (secs % 3600) / 60;
+            let second = secs % 60;
+            format!(
+                "{:04}-{:02}-{:02}T{:02}:{:02}:{:02}Z",
+                1970 + years,
+                month + 1,
+                day,
+                hour,
+                minute,
+                second,
+            )
+        })
+        .unwrap_or_else(|_| "1970-01-01T00:00:00Z".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_session_basic() {
+        let mut session = Session::new();
+
+        let msg1 = SessionEntry::user_message(None, "Hello");
+        let msg1_id = msg1.id();
+        session.push(msg1);
+
+        let msg2 = SessionEntry::assistant_message(Some(msg1_id), "Hi there!", None);
+        session.push(msg2);
+
+        assert_eq!(session.entry_count(), 2);
+        assert_eq!(session.active_branch().len(), 2);
+    }
+
+    #[test]
+    fn test_session_fork() {
+        let mut session = Session::new();
+
+        let msg1 = SessionEntry::user_message(None, "First");
+        let msg1_id = msg1.id();
+        session.push(msg1);
+
+        let msg2 = SessionEntry::assistant_message(Some(msg1_id), "Reply 1", None);
+        let msg2_id = msg2.id();
+        session.push(msg2);
+
+        let msg3 = SessionEntry::user_message(Some(msg2_id), "Second");
+        session.push(msg3);
+
+        // Fork from msg2
+        let forked = session.fork_from(msg2_id).unwrap();
+        assert_eq!(forked.entry_count(), 2);
+        assert_eq!(forked.header.parent_session, Some(session.header.id));
+    }
+
+    #[test]
+    fn test_session_leaves() {
+        let mut session = Session::new();
+
+        let msg1 = SessionEntry::user_message(None, "Root");
+        let msg1_id = msg1.id();
+        session.push(msg1);
+
+        // Two children branching from root
+        let msg2a = SessionEntry::assistant_message(Some(msg1_id), "Branch A", None);
+        let msg2b = SessionEntry::assistant_message(Some(msg1_id), "Branch B", None);
+        session.push(msg2a);
+        session.push(msg2b);
+
+        let leaves = session.leaves();
+        assert_eq!(leaves.len(), 2);
+    }
+}
diff --git a/lib/ai/agent/subagent.rs b/lib/ai/agent/subagent.rs
new file mode 100644
index 0000000..f23758d
--- /dev/null
+++ b/lib/ai/agent/subagent.rs
@@ -0,0 +1,203 @@
+use rig::agent::AgentBuilder;
+use rig::client::CompletionClient;
+use rig::completion::Prompt;
+use tracing::{debug, warn};
+
+use super::config::AgentConfig;
+use super::helpers::with_retry;
+use super::persistence::{
+    ActiveAgentRun, AgentRealtime, AgentRuntime, AgentStreamEvent,
+    estimate_output_tokens,
+};
+use super::request::{AgentExpert, AgentExpertOutput};
+use crate::client::AiClient;
+use crate::error::{AiError, AiResult};
+
+pub async fn run_experts(
+    client: &AiClient,
+    config: &AgentConfig,
+    experts: &[AgentExpert],
+    realtime: Option<&AgentRealtime>,
+    run: &ActiveAgentRun,
+) -> AiResult<Vec<AgentExpertOutput>> {
+    let mut outputs = Vec::with_capacity(experts.len());
+    let mut failed_count = 0;
+
+    for expert in experts {
+        match run_single(client, config, expert, realtime, run).await {
+            Ok(output) => {
+                debug!(subagent_id = %output.id, role = %output.role, "subagent completed");
+                outputs.push(output);
+            }
+            Err(error) => {
+                warn!(subagent_id = %expert.id, role = %expert.role, error = %error, "subagent failed");
+                let _ = publish_subagent_failed(realtime, run, expert, &error.to_string()).await;
+                failed_count += 1;
+            }
+        }
+    }
+
+    debug!(total = experts.len(), ok = outputs.len(), failed = failed_count, "experts done");
+    Ok(outputs)
+}
+
+async fn run_single(
+    client: &AiClient,
+    config: &AgentConfig,
+    expert: &AgentExpert,
+    realtime: Option<&AgentRealtime>,
+    run: &ActiveAgentRun,
+) -> AiResult<AgentExpertOutput> {
+    publish_subagent_started(realtime, run, config, expert).await?;
+
+    let rig_client = client.llm_client().clone();
+    let model_name = config.model.clone();
+    let temperature = expert.temperature.or(config.temperature);
+    let max_completion_tokens = expert.max_completion_tokens.or(config.max_completion_tokens);
+    let retry_attempts = config.retry_max_attempts;
+    let retry_delay_ms = config.retry_base_delay_ms;
+
+    let prompt = expert.system_prompt.clone().unwrap_or_else(|| {
+        format!(
+            "You are a specialist subagent. Role: {}. Produce a concise expert answer for the parent chat agent.",
+            expert.role
+        )
+    });
+
+    let task = build_expert_task(expert);
+
+    let (output, input_tokens_usage, output_tokens_usage) = with_retry(
+        retry_attempts,
+        retry_delay_ms,
+        || {
+            let rig_client = rig_client.clone();
+            let model_name = model_name.clone();
+            let prompt = prompt.clone();
+            let task = task.clone();
+            async move {
+                let model = rig_client.completion_model(&model_name);
+                let mut builder = AgentBuilder::new(model).preamble(&prompt);
+                if let Some(temp) = temperature {
+                    builder = builder.temperature(temp);
+                }
+                if let Some(mt) = max_completion_tokens {
+                    builder = builder.max_tokens(mt);
+                }
+                let agent = builder.build();
+
+                let response = agent
+                    .prompt(&task)
+                    .extended_details()
+                    .await
+                    .map_err(|e: rig::completion::PromptError| {
+                        AiError::Api(e.to_string())
+                    })?;
+
+                Ok((
+                    response.output,
+                    response.usage.input_tokens,
+                    response.usage.output_tokens,
+                ))
+            }
+        },
+    )
+    .await?;
+
+    let input_tokens = input_tokens_usage as i64;
+    let output_tokens = if output_tokens_usage > 0 {
+        output_tokens_usage as i64
+    } else {
+        estimate_output_tokens(&output)
+    };
+
+    let result = AgentExpertOutput {
+        id: expert.id.clone(),
+        role: expert.role.clone(),
+        task: expert.task.clone(),
+        output,
+        input_tokens,
+        output_tokens,
+    };
+
+    publish_subagent_completed(realtime, run, config, &result).await?;
+    Ok(result)
+}
+
+fn build_expert_task(expert: &AgentExpert) -> String {
+    let mut task = String::new();
+
+    if !expert.context.is_empty() {
+        task.push_str("Retrieved context for this specialist task:\n");
+        for (index, chunk) in expert.context.iter().enumerate() {
+            task.push_str(&format!(
+                "\n[{}] id={} source={}\n{}\n",
+                index + 1,
+                chunk.id,
+                chunk.source.as_deref().unwrap_or("unknown"),
+                chunk.content
+            ));
+        }
+        task.push('\n');
+    }
+
+    task.push_str(&expert.task);
+    task
+}
+
+async fn publish_subagent_started(
+    realtime: Option<&AgentRealtime>,
+    run: &ActiveAgentRun,
+    config: &AgentConfig,
+    expert: &AgentExpert,
+) -> AiResult<()> {
+    AgentRuntime::default().publish(
+        realtime,
+        &AgentStreamEvent::SubagentStarted {
+            conversation_id: run.conversation_id,
+            message_id: run.message_id,
+            subagent_id: expert.id.clone(),
+            role: expert.role.clone(),
+            task: expert.task.clone(),
+            model: config.model.clone(),
+        },
+    ).await
+}
+
+async fn publish_subagent_completed(
+    realtime: Option<&AgentRealtime>,
+    run: &ActiveAgentRun,
+    config: &AgentConfig,
+    output: &AgentExpertOutput,
+) -> AiResult<()> {
+    AgentRuntime::default().publish(
+        realtime,
+        &AgentStreamEvent::SubagentCompleted {
+            conversation_id: run.conversation_id,
+            message_id: run.message_id,
+            subagent_id: output.id.clone(),
+            role: output.role.clone(),
+            task: output.task.clone(),
+            output: output.output.clone(),
+            input_tokens: output.input_tokens,
+            output_tokens: output.output_tokens,
+            model: config.model.clone(),
+        },
+    ).await
+}
+
+async fn publish_subagent_failed(
+    realtime: Option<&AgentRealtime>,
+    run: &ActiveAgentRun,
+    expert: &AgentExpert,
+    error: &str,
+) -> AiResult<()> {
+    AgentRuntime::default().publish(
+        realtime,
+        &AgentStreamEvent::SubagentFailed {
+            conversation_id: run.conversation_id,
+            message_id: run.message_id,
+            subagent_id: expert.id.clone(),
+            error: error.to_string(),
+        },
+    ).await
+}
diff --git a/lib/ai/agent/tool.rs b/lib/ai/agent/tool.rs
new file mode 100644
index 0000000..08d9c75
--- /dev/null
+++ b/lib/ai/agent/tool.rs
@@ -0,0 +1,158 @@
+use std::pin::Pin;
+use std::sync::Arc;
+
+use rig::completion::ToolDefinition as RigToolDefinition;
+use rig::tool::ToolDyn;
+use serde_json::Value;
+use tokio::sync::Mutex;
+
+use crate::tool::tools::FunctionCall;
+
+pub struct RigTool<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    context: Arc<Mutex<C>>,
+    tool: Arc<dyn FunctionCall<Context = C>>,
+    name: String,
+    description: String,
+    schema: Value,
+}
+
+impl<C> RigTool<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    pub fn new(tool: Arc<dyn FunctionCall<Context = C>>, context: Arc<Mutex<C>>) -> Self {
+        let name = tool.name().to_string();
+        let description = tool.description().to_string();
+        let schema = tool.schema();
+
+        Self {
+            context,
+            tool,
+            name,
+            description,
+            schema,
+        }
+    }
+}
+
+impl<C> ToolDyn for RigTool<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    fn name(&self) -> String {
+        self.name.clone()
+    }
+
+    fn definition<'a>(
+        &'a self,
+        _prompt: String,
+    ) -> Pin<Box<dyn std::future::Future<Output = RigToolDefinition> + Send + 'a>> {
+        let name = self.name.clone();
+        let description = self.description.clone();
+        let params = self.schema.clone();
+
+        Box::pin(async move {
+            RigToolDefinition {
+                name,
+                description,
+                parameters: params,
+            }
+        })
+    }
+
+    fn call<'a>(
+        &'a self,
+        args: String,
+    ) -> Pin<
+        Box<dyn std::future::Future<Output = Result<String, rig::tool::ToolError>> + Send + 'a>,
+    > {
+        let tool = self.tool.clone();
+        let context = self.context.clone();
+
+        Box::pin(async move {
+            let args_value: Value =
+                serde_json::from_str(&args).map_err(rig::tool::ToolError::JsonError)?;
+
+            let mut ctx = context.lock().await;
+
+            match tool.call(&mut *ctx, args_value).await {
+                Ok(value) => serde_json::to_string(&value)
+                    .map_err(rig::tool::ToolError::JsonError),
+                Err(ai_err) => Err(rig::tool::ToolError::ToolCallError(Box::new(
+                    std::io::Error::other(ai_err.to_string()),
+                ))),
+            }
+        })
+    }
+}
+
+pub struct RigToolSet<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    tools: Vec<Box<dyn ToolDyn + 'static>>,
+    context: Option<Arc<Mutex<C>>>,
+}
+
+impl<C> RigToolSet<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    pub fn new() -> Self {
+        Self {
+            tools: Vec::new(),
+            context: None,
+        }
+    }
+
+    pub fn from_register(
+        register: &crate::tool::register::ToolRegister<C>,
+        context: Arc<Mutex<C>>,
+    ) -> Self {
+        let mut tools: Vec<Box<dyn ToolDyn + 'static>> = Vec::with_capacity(register.len());
+
+        for tool_arc in &register.tools {
+            tools.push(Box::new(RigTool::new(tool_arc.clone(), context.clone())));
+        }
+
+        Self {
+            tools,
+            context: Some(context),
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.tools.is_empty()
+    }
+
+    pub fn len(&self) -> usize {
+        self.tools.len()
+    }
+
+    pub fn context(&self) -> Option<&Arc<Mutex<C>>> {
+        self.context.as_ref()
+    }
+
+    pub fn take_tools(&mut self) -> Vec<Box<dyn ToolDyn + 'static>> {
+        std::mem::take(&mut self.tools)
+    }
+
+    pub fn into_context(mut self) -> C {
+        self.context
+            .take()
+            .and_then(|arc| Arc::try_unwrap(arc).ok().map(|m| m.into_inner()))
+            .unwrap_or_else(|| unreachable!("context must be available"))
+    }
+}
+
+impl<C> Default for RigToolSet<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/lib/ai/client.rs b/lib/ai/client.rs
new file mode 100644
index 0000000..25a2678
--- /dev/null
+++ b/lib/ai/client.rs
@@ -0,0 +1,219 @@
+use std::fmt;
+use std::sync::Arc;
+
+use config::AppConfig;
+use rig::providers::openai;
+
+use crate::error::{AiError, AiResult};
+
+fn validate_required(scope: &str, field: &str, value: &str) -> AiResult<()> {
+    if value.trim().is_empty() {
+        return Err(AiError::Config(format!("{scope} {field} is required")));
+    }
+    Ok(())
+}
+
+fn config_error(error: impl fmt::Display) -> AiError {
+    AiError::Config(error.to_string())
+}
+
+#[derive(Clone)]
+pub struct EndpointConfig {
+    pub base_url: String,
+    pub api_key: String,
+}
+
+impl EndpointConfig {
+    pub fn new(base_url: impl Into<String>, api_key: impl Into<String>) -> AiResult<Self> {
+        let config = Self {
+            base_url: base_url.into(),
+            api_key: api_key.into(),
+        };
+        config.validate("endpoint")?;
+        Ok(config)
+    }
+
+    fn validate(&self, scope: &str) -> AiResult<()> {
+        validate_required(scope, "base_url", &self.base_url)?;
+        validate_required(scope, "api_key", &self.api_key)?;
+        if !self.base_url.trim().starts_with("http://")
+            && !self.base_url.trim().starts_with("https://")
+        {
+            return Err(AiError::Config(format!(
+                "{scope} base_url must start with http:// or https://"
+            )));
+        }
+        Ok(())
+    }
+
+    pub fn build_client(&self) -> AiResult<openai::Client> {
+        openai::Client::builder()
+            .api_key(&self.api_key)
+            .base_url(self.base_url.trim())
+            .build()
+            .map_err(|e| AiError::Config(format!("failed to build rig OpenAI client: {e}")))
+    }
+}
+
+impl fmt::Debug for EndpointConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("EndpointConfig")
+            .field("base_url", &self.base_url)
+            .field("api_key", &"<redacted>")
+            .finish()
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct EmbedConfig {
+    pub endpoint: EndpointConfig,
+    pub model: String,
+    pub dimensions: u64,
+}
+
+impl EmbedConfig {
+    pub fn new(
+        endpoint: EndpointConfig,
+        model: impl Into<String>,
+        dimensions: u64,
+    ) -> AiResult<Self> {
+        let config = Self {
+            endpoint,
+            model: model.into(),
+            dimensions,
+        };
+        config.validate()?;
+        Ok(config)
+    }
+
+    fn validate(&self) -> AiResult<()> {
+        self.endpoint.validate("embed endpoint")?;
+        validate_required("embed", "model", &self.model)?;
+        if self.dimensions == 0 {
+            return Err(AiError::Config(
+                "embed dimensions must be greater than 0".to_string(),
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct AiClientConfig {
+    pub llm: EndpointConfig,
+    pub embed: EmbedConfig,
+}
+
+impl AiClientConfig {
+    pub fn new(llm: EndpointConfig, embed: EmbedConfig) -> AiResult<Self> {
+        let config = Self { llm, embed };
+        config.validate()?;
+        Ok(config)
+    }
+
+    pub fn validate(&self) -> AiResult<()> {
+        self.llm.validate("llm endpoint")?;
+        self.embed.validate()?;
+        Ok(())
+    }
+}
+
+impl TryFrom<&AppConfig> for AiClientConfig {
+    type Error = AiError;
+
+    fn try_from(config: &AppConfig) -> Result<Self, Self::Error> {
+        let llm = EndpointConfig::new(
+            config.ai_basic_url().map_err(config_error)?,
+            config.ai_api_key().map_err(config_error)?,
+        )?;
+
+        let embed_endpoint = EndpointConfig::new(
+            config.get_embed_model_base_url().map_err(config_error)?,
+            config.get_embed_model_api_key().map_err(config_error)?,
+        )?;
+
+        let embed = EmbedConfig::new(
+            embed_endpoint,
+            config.get_embed_model_name().map_err(config_error)?,
+            config.get_embed_model_dimensions().map_err(config_error)?,
+        )?;
+
+        Self::new(llm, embed)
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct AiClient {
+    pub(super) llm_client: openai::Client,
+    pub(super) embed_client: openai::Client,
+    pub(super) config: Arc<AiClientConfig>,
+}
+
+impl AiClient {
+    pub fn new(config: AiClientConfig) -> AiResult<Self> {
+        config.validate()?;
+
+        Ok(Self {
+            llm_client: config.llm.build_client()?,
+            embed_client: config.embed.endpoint.build_client()?,
+            config: Arc::new(config),
+        })
+    }
+
+    pub fn from_app_config(config: &AppConfig) -> AiResult<Self> {
+        Self::new(AiClientConfig::try_from(config)?)
+    }
+
+    pub fn llm_client(&self) -> &openai::Client {
+        &self.llm_client
+    }
+
+    pub fn embed_client(&self) -> &openai::Client {
+        &self.embed_client
+    }
+
+    pub fn config(&self) -> &AiClientConfig {
+        &self.config
+    }
+
+    pub fn llm_config(&self) -> &EndpointConfig {
+        &self.config.llm
+    }
+
+    pub fn embed_config(&self) -> &EmbedConfig {
+        &self.config.embed
+    }
+
+    pub fn embed_model(&self) -> &str {
+        self.config.embed.model.as_str()
+    }
+
+    pub fn embed_dimensions(&self) -> u64 {
+        self.config.embed.dimensions
+    }
+
+    pub fn embed_dimensions_u32(&self) -> u32 {
+        u32::try_from(self.config.embed.dimensions).unwrap_or(u32::MAX)
+    }
+}
+
+pub fn build_http_client() -> Result<reqwest::Client, AiError> {
+    let mut builder = reqwest::Client::builder();
+
+    if let Ok(proxy_url) = std::env::var("HTTPS_PROXY")
+        .or_else(|_| std::env::var("https_proxy"))
+        .or_else(|_| std::env::var("HTTP_PROXY"))
+        .or_else(|_| std::env::var("http_proxy"))
+    {
+        let proxy_url = proxy_url.trim().trim_matches('"').trim_matches('\'');
+        let proxy = reqwest::Proxy::all(proxy_url).map_err(|e| {
+            AiError::Config(format!("Invalid proxy URL '{}': {}", proxy_url, e))
+        })?;
+        builder = builder.proxy(proxy);
+    }
+
+    builder.build().map_err(|e| {
+        AiError::Config(format!("Failed to build HTTP client: {}", e))
+    })
+}
diff --git a/lib/ai/embed/client.rs b/lib/ai/embed/client.rs
new file mode 100644
index 0000000..f250cf4
--- /dev/null
+++ b/lib/ai/embed/client.rs
@@ -0,0 +1,76 @@
+use rig::client::EmbeddingsClient;
+use rig::embeddings::EmbeddingModel;
+
+use crate::{client::AiClient, error::{AiError, AiResult}};
+
+#[derive(Clone)]
+pub struct EmbedClient {
+    model_name: String,
+    client: rig::providers::openai::Client,
+}
+
+impl EmbedClient {
+    pub fn new(ai_client: &AiClient) -> AiResult<Self> {
+        Ok(Self {
+            model_name: ai_client.embed_model().to_string(),
+            client: ai_client.embed_client().clone(),
+        })
+    }
+
+    fn embedding_model(&self) -> impl EmbeddingModel + '_ {
+        self.client.embedding_model(&self.model_name)
+    }
+
+    pub async fn embed_text(&self, text: String) -> AiResult<Vec<f32>> {
+        let model = self.embedding_model();
+        let mut embeddings = model.embed_texts(vec![text])
+            .await
+            .map_err(|e| AiError::Api(e.to_string()))?;
+        embeddings.pop()
+            .map(|e| e.vec.into_iter().map(|v| v as f32).collect())
+            .ok_or_else(|| AiError::Response("no embedding returned".to_string()))
+    }
+
+    pub async fn embed_texts(&self, texts: Vec<String>) -> AiResult<Vec<Vec<f32>>> {
+        if texts.is_empty() {
+            return Ok(Vec::new());
+        }
+        let model = self.embedding_model();
+        let embeddings = model.embed_texts(texts)
+            .await
+            .map_err(|e| AiError::Api(e.to_string()))?;
+        Ok(embeddings.into_iter()
+            .map(|e| e.vec.into_iter().map(|v| v as f32).collect())
+            .collect())
+    }
+
+    pub async fn embed_texts_chunked(
+        &self,
+        texts: Vec<String>,
+        batch_size: usize,
+    ) -> AiResult<Vec<Vec<f32>>> {
+        if batch_size == 0 {
+            return Err(AiError::Config("batch_size must be > 0".to_string()));
+        }
+        let mut embeddings: Vec<Vec<f32>> = Vec::with_capacity(texts.len());
+        for chunk in texts.chunks(batch_size) {
+            let model = self.embedding_model();
+            let chunk_embeddings = model.embed_texts(chunk.to_vec())
+                .await
+                .map_err(|e| AiError::Api(e.to_string()))?;
+            embeddings.extend(chunk_embeddings.into_iter()
+                .map(|e| e.vec.into_iter().map(|v| v as f32).collect()));
+        }
+        Ok(embeddings)
+    }
+}
+
+pub trait AiClientEmbedExt {
+    fn embedder(&self) -> AiResult<EmbedClient>;
+}
+
+impl AiClientEmbedExt for AiClient {
+    fn embedder(&self) -> AiResult<EmbedClient> {
+        EmbedClient::new(self)
+    }
+}
diff --git a/lib/ai/embed/mod.rs b/lib/ai/embed/mod.rs
new file mode 100644
index 0000000..18a300e
--- /dev/null
+++ b/lib/ai/embed/mod.rs
@@ -0,0 +1,3 @@
+mod client;
+
+pub use client::{AiClientEmbedExt, EmbedClient};
diff --git a/lib/ai/error.rs b/lib/ai/error.rs
new file mode 100644
index 0000000..f41f408
--- /dev/null
+++ b/lib/ai/error.rs
@@ -0,0 +1,52 @@
+pub type AiResult<T> = Result<T, AiError>;
+
+#[derive(Debug, thiserror::Error)]
+pub enum AiError {
+    #[error("ai config error: {0}")]
+    Config(String),
+
+    #[error("ai api error: {0}")]
+    Api(String),
+
+    #[error("qdrant error: {0}")]
+    Qdrant(Box<qdrant_client::QdrantError>),
+
+    #[error("database error: {0}")]
+    Database(#[from] db::sqlx::Error),
+
+    #[error("cache error: {0}")]
+    Cache(#[from] cache::CacheError),
+
+    #[error("redis error: {0}")]
+    Redis(#[from] redis::RedisError),
+
+    #[error("ai response error: {0}")]
+    Response(String),
+
+    #[error("model retries exhausted after {attempts} attempts: {last_error}")]
+    ModelRetriesExhausted {
+        attempts: usize,
+        last_error: String,
+    },
+
+    #[error("agent timeout after {seconds}s")]
+    Timeout { seconds: u64 },
+
+    #[error("tool not found: {tool}")]
+    ToolNotFound { tool: String },
+
+    #[error("tool execution failed: {cause}")]
+    ToolExecutionFailed { cause: String },
+
+    #[error("invalid input in '{field}': {reason}")]
+    InvalidInput { field: String, reason: String },
+
+    #[error("token budget exceeded: used ~{estimated} tokens, limit {limit}")]
+    TokenBudgetExceeded { estimated: u64, limit: i64 },
+}
+
+impl From<qdrant_client::QdrantError> for AiError {
+    fn from(e: qdrant_client::QdrantError) -> Self {
+        AiError::Qdrant(Box::new(e))
+    }
+}
diff --git a/lib/ai/lib.rs b/lib/ai/lib.rs
new file mode 100644
index 0000000..bc51824
--- /dev/null
+++ b/lib/ai/lib.rs
@@ -0,0 +1,8 @@
+pub mod agent;
+pub mod client;
+pub mod embed;
+pub mod error;
+pub mod memory;
+pub mod rag;
+pub mod sync;
+pub mod tool;
diff --git a/lib/ai/memory/mod.rs b/lib/ai/memory/mod.rs
new file mode 100644
index 0000000..45a5c31
--- /dev/null
+++ b/lib/ai/memory/mod.rs
@@ -0,0 +1,46 @@
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::error::AiResult;
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemoryEntry {
+    pub key: String,
+    pub value: String,
+    pub importance: i32,
+    pub last_used_at: Option<String>,
+}
+#[async_trait]
+pub trait MemoryProvider: Send + Sync {
+    fn name(&self) -> &'static str;
+    async fn save(
+        &self,
+        session_id: Uuid,
+        key: &str,
+        value: &str,
+        importance: i32,
+    ) -> AiResult<()>;
+    async fn recall(
+        &self,
+        session_id: Uuid,
+        query: &str,
+        limit: usize,
+    ) -> AiResult<Vec<MemoryEntry>>;
+    async fn forget(&self, session_id: Uuid, key: &str) -> AiResult<()>;
+    async fn prefetch(
+        &self,
+        _session_id: Uuid,
+        _query: &str,
+    ) -> AiResult<Vec<MemoryEntry>> {
+        Ok(Vec::new())
+    }
+    async fn build_context_block(
+        &self,
+        _session_id: Uuid,
+    ) -> AiResult<String> {
+        Ok(String::new())
+    }
+    async fn setup(&self) -> AiResult<()> {
+        Ok(())
+    }
+}
diff --git a/lib/ai/rag/client.rs b/lib/ai/rag/client.rs
new file mode 100644
index 0000000..c4da99b
--- /dev/null
+++ b/lib/ai/rag/client.rs
@@ -0,0 +1,263 @@
+use config::AppConfig;
+use qdrant_client::qdrant::{
+    CreateCollectionBuilder, CreateFieldIndexCollectionBuilder,
+    DeletePointsBuilder, FieldType, PointStruct, QueryPointsBuilder,
+    SearchParamsBuilder, UpsertPointsBuilder, VectorParamsBuilder,
+};
+use qdrant_client::{Qdrant, QdrantError};
+
+use super::{
+    config::RagConfig,
+    document::{RagDocument, RagSearchHit},
+    payload::{
+        SESSION_ID_KEY, document_payload, hit_from_scored_point, point_id,
+    },
+    search::RagSearchOptions,
+    session::{session_filter, validate_session_id},
+};
+use crate::{
+    client::AiClient,
+    embed::{AiClientEmbedExt, EmbedClient},
+    error::{AiError, AiResult},
+};
+
+#[derive(Clone)]
+pub struct RagClient {
+    qdrant: Qdrant,
+    embedder: EmbedClient,
+    config: RagConfig,
+}
+
+impl RagClient {
+    pub fn new(
+        qdrant: Qdrant,
+        embedder: EmbedClient,
+        config: RagConfig,
+    ) -> AiResult<Self> {
+        config.validate()?;
+        Ok(Self {
+            qdrant,
+            embedder,
+            config,
+        })
+    }
+
+    pub fn connect(
+        ai_client: &AiClient,
+        config: RagConfig,
+    ) -> AiResult<Self> {
+        config.validate()?;
+        let mut builder =
+            Qdrant::from_url(config.url.trim()).timeout(config.timeout);
+        if let Some(api_key) = config
+            .api_key
+            .as_deref()
+            .filter(|api_key| !api_key.trim().is_empty())
+        {
+            builder = builder.api_key(api_key);
+        }
+
+        Self::new(builder.build()?, ai_client.embedder()?, config)
+    }
+
+    pub fn from_app_config(
+        ai_client: &AiClient,
+        config: &AppConfig,
+        collection_name: impl Into<String>,
+    ) -> AiResult<Self> {
+        Self::connect(
+            ai_client,
+            RagConfig::from_app_config(config, collection_name)?,
+        )
+    }
+
+    pub fn qdrant(&self) -> &Qdrant {
+        &self.qdrant
+    }
+
+    pub fn embedder(&self) -> &EmbedClient {
+        &self.embedder
+    }
+
+    pub fn config(&self) -> &RagConfig {
+        &self.config
+    }
+
+    pub async fn ensure_collection(&self) -> AiResult<()> {
+        if !self
+            .qdrant
+            .collection_exists(&self.config.collection_name)
+            .await?
+        {
+            self.qdrant
+                .create_collection(
+                    CreateCollectionBuilder::new(&self.config.collection_name)
+                        .vectors_config(VectorParamsBuilder::new(
+                            self.config.vector_size,
+                            self.config.distance,
+                        )),
+                )
+                .await?;
+        }
+
+        match self
+            .qdrant
+            .create_field_index(CreateFieldIndexCollectionBuilder::new(
+                &self.config.collection_name,
+                SESSION_ID_KEY,
+                FieldType::Keyword,
+            ))
+            .await
+        {
+            Ok(_) => Ok(()),
+            Err(QdrantError::ResponseError { .. }) => Ok(()),
+            Err(error) => Err(error.into()),
+        }
+    }
+
+    pub async fn upsert_document(
+        &self,
+        session_id: impl AsRef<str>,
+        document: RagDocument,
+    ) -> AiResult<()> {
+        self.upsert_documents(session_id, vec![document]).await
+    }
+
+    pub async fn upsert_documents(
+        &self,
+        session_id: impl AsRef<str>,
+        documents: Vec<RagDocument>,
+    ) -> AiResult<()> {
+        let session_id = session_id.as_ref();
+        validate_session_id(session_id)?;
+        validate_documents(&documents)?;
+
+        let texts: Vec<String> = documents
+            .iter()
+            .map(|d| d.content.clone())
+            .collect();
+        let vectors = self
+            .embedder
+            .embed_texts_chunked(texts, self.config.upsert_batch_size)
+            .await?;
+
+        let points = documents
+            .iter()
+            .zip(vectors)
+            .map(|(document, vector)| {
+                Ok(PointStruct::new(
+                    point_id(session_id, &document.id),
+                    vector,
+                    document_payload(session_id, document)?,
+                ))
+            })
+            .collect::<AiResult<Vec<_>>>()?;
+
+        self.qdrant
+            .upsert_points(
+                UpsertPointsBuilder::new(&self.config.collection_name, points)
+                    .wait(true),
+            )
+            .await?;
+
+        Ok(())
+    }
+
+    pub async fn search_session(
+        &self,
+        session_id: impl AsRef<str>,
+        query: impl Into<String>,
+    ) -> AiResult<Vec<RagSearchHit>> {
+        let options = RagSearchOptions {
+            limit: self.config.default_search_limit,
+            exact: self.config.exact_session_search,
+        };
+        self.search_session_with_options(session_id, query, options)
+            .await
+    }
+
+    pub async fn search_session_with_options(
+        &self,
+        session_id: impl AsRef<str>,
+        query: impl Into<String>,
+        options: RagSearchOptions,
+    ) -> AiResult<Vec<RagSearchHit>> {
+        let vector = self.embedder.embed_text(query.into()).await?;
+        self.search_session_by_vector(session_id, vector, options)
+            .await
+    }
+
+    pub async fn search_session_by_vector(
+        &self,
+        session_id: impl AsRef<str>,
+        vector: Vec<f32>,
+        options: RagSearchOptions,
+    ) -> AiResult<Vec<RagSearchHit>> {
+        let session_id = session_id.as_ref();
+        validate_session_id(session_id)?;
+        if options.limit == 0 {
+            return Err(AiError::Config(
+                "rag search limit must be greater than 0".to_string(),
+            ));
+        }
+
+        let response = self
+            .qdrant
+            .query(
+                QueryPointsBuilder::new(&self.config.collection_name)
+                    .query(vector)
+                    .limit(options.limit)
+                    .filter(session_filter(session_id))
+                    .with_payload(true)
+                    .params(
+                        SearchParamsBuilder::default().exact(options.exact),
+                    ),
+            )
+            .await?;
+
+        Ok(response
+            .result
+            .into_iter()
+            .map(hit_from_scored_point)
+            .collect())
+    }
+
+    pub async fn clear_session(
+        &self,
+        session_id: impl AsRef<str>,
+    ) -> AiResult<()> {
+        let session_id = session_id.as_ref();
+        validate_session_id(session_id)?;
+
+        self.qdrant
+            .delete_points(
+                DeletePointsBuilder::new(&self.config.collection_name)
+                    .points(session_filter(session_id))
+                    .wait(true),
+            )
+            .await?;
+
+        Ok(())
+    }
+}
+
+fn validate_documents(documents: &[RagDocument]) -> AiResult<()> {
+    if documents.is_empty() {
+        return Err(AiError::Config("rag documents are required".to_string()));
+    }
+
+    for document in documents {
+        if document.id.trim().is_empty() {
+            return Err(AiError::Config(
+                "rag document id is required".to_string(),
+            ));
+        }
+        if document.content.trim().is_empty() {
+            return Err(AiError::Config(
+                "rag document content is required".to_string(),
+            ));
+        }
+    }
+
+    Ok(())
+}
diff --git a/lib/ai/rag/config.rs b/lib/ai/rag/config.rs
new file mode 100644
index 0000000..bd9bcab
--- /dev/null
+++ b/lib/ai/rag/config.rs
@@ -0,0 +1,134 @@
+use std::time::Duration;
+
+use config::AppConfig;
+use qdrant_client::qdrant::Distance;
+
+use crate::error::{AiError, AiResult};
+
+#[derive(Clone, Debug)]
+pub struct RagConfig {
+    pub url: String,
+    pub api_key: Option<String>,
+    pub collection_name: String,
+    pub vector_size: u64,
+    pub distance: Distance,
+    pub timeout: Duration,
+    pub upsert_batch_size: usize,
+    pub default_search_limit: u64,
+    pub exact_session_search: bool,
+}
+
+impl RagConfig {
+    pub fn new(
+        url: impl Into<String>,
+        collection_name: impl Into<String>,
+        vector_size: u64,
+    ) -> AiResult<Self> {
+        let config = Self {
+            url: url.into(),
+            api_key: None,
+            collection_name: collection_name.into(),
+            vector_size,
+            distance: Distance::Cosine,
+            timeout: Duration::from_secs(10),
+            upsert_batch_size: 64,
+            default_search_limit: 8,
+            exact_session_search: true,
+        };
+        config.validate()?;
+        Ok(config)
+    }
+
+    pub fn with_api_key(mut self, api_key: Option<String>) -> Self {
+        self.api_key = api_key;
+        self
+    }
+
+    pub fn with_distance(mut self, distance: Distance) -> Self {
+        self.distance = distance;
+        self
+    }
+
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    pub fn with_upsert_batch_size(mut self, upsert_batch_size: usize) -> Self {
+        self.upsert_batch_size = upsert_batch_size;
+        self
+    }
+
+    pub fn with_default_search_limit(
+        mut self,
+        default_search_limit: u64,
+    ) -> Self {
+        self.default_search_limit = default_search_limit;
+        self
+    }
+
+    pub fn with_exact_session_search(
+        mut self,
+        exact_session_search: bool,
+    ) -> Self {
+        self.exact_session_search = exact_session_search;
+        self
+    }
+
+    pub fn validate(&self) -> AiResult<()> {
+        if self.url.trim().is_empty() {
+            return Err(AiError::Config("qdrant url is required".to_string()));
+        }
+        if !self.url.trim().starts_with("http://")
+            && !self.url.trim().starts_with("https://")
+        {
+            return Err(AiError::Config(
+                "qdrant url must start with http:// or https://".to_string(),
+            ));
+        }
+        if self.collection_name.trim().is_empty() {
+            return Err(AiError::Config(
+                "qdrant collection_name is required".to_string(),
+            ));
+        }
+        if self.vector_size == 0 {
+            return Err(AiError::Config(
+                "qdrant vector_size must be greater than 0".to_string(),
+            ));
+        }
+        if self.upsert_batch_size == 0 {
+            return Err(AiError::Config(
+                "qdrant upsert_batch_size must be greater than 0".to_string(),
+            ));
+        }
+        if self.default_search_limit == 0 {
+            return Err(AiError::Config(
+                "qdrant default_search_limit must be greater than 0"
+                    .to_string(),
+            ));
+        }
+        Ok(())
+    }
+}
+
+impl RagConfig {
+    pub fn from_app_config(
+        config: &AppConfig,
+        collection_name: impl Into<String>,
+    ) -> AiResult<Self> {
+        Ok(Self::new(
+            config
+                .qdrant_url()
+                .map_err(|error| AiError::Config(error.to_string()))?,
+            collection_name,
+            config
+                .get_embed_model_dimensions()
+                .map_err(|error| AiError::Config(error.to_string()))?,
+        )?
+        .with_api_key(
+            config
+                .qdrant_api_key()
+                .map_err(|error| AiError::Config(error.to_string()))?,
+        ))
+    }
+}
diff --git a/lib/ai/rag/document.rs b/lib/ai/rag/document.rs
new file mode 100644
index 0000000..c56422c
--- /dev/null
+++ b/lib/ai/rag/document.rs
@@ -0,0 +1,44 @@
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct RagDocument {
+    pub id: String,
+    pub content: String,
+    pub metadata: HashMap<String, Value>,
+}
+
+impl RagDocument {
+    pub fn new(id: impl Into<String>, content: impl Into<String>) -> Self {
+        Self {
+            id: id.into(),
+            content: content.into(),
+            metadata: HashMap::new(),
+        }
+    }
+
+    pub fn with_metadata(mut self, metadata: HashMap<String, Value>) -> Self {
+        self.metadata = metadata;
+        self
+    }
+
+    pub fn metadata_value(
+        mut self,
+        key: impl Into<String>,
+        value: impl Into<Value>,
+    ) -> Self {
+        self.metadata.insert(key.into(), value.into());
+        self
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct RagSearchHit {
+    pub id: String,
+    pub session_id: String,
+    pub score: f32,
+    pub content: String,
+    pub metadata: HashMap<String, Value>,
+}
diff --git a/lib/ai/rag/mod.rs b/lib/ai/rag/mod.rs
new file mode 100644
index 0000000..ba16d88
--- /dev/null
+++ b/lib/ai/rag/mod.rs
@@ -0,0 +1,11 @@
+mod client;
+mod config;
+mod document;
+mod payload;
+mod search;
+mod session;
+
+pub use client::RagClient;
+pub use config::RagConfig;
+pub use document::{RagDocument, RagSearchHit};
+pub use search::RagSearchOptions;
diff --git a/lib/ai/rag/payload.rs b/lib/ai/rag/payload.rs
new file mode 100644
index 0000000..d8bb6e9
--- /dev/null
+++ b/lib/ai/rag/payload.rs
@@ -0,0 +1,110 @@
+use std::collections::HashMap;
+
+use qdrant_client::Payload;
+use qdrant_client::qdrant::{
+    PointId, ScoredPoint, point_id::PointIdOptions, value::Kind,
+};
+use serde_json::{Map, Value, json};
+use uuid::Uuid;
+
+use super::document::{RagDocument, RagSearchHit};
+use crate::error::{AiError, AiResult};
+
+pub(super) const SESSION_ID_KEY: &str = "session_id";
+pub(super) const DOCUMENT_ID_KEY: &str = "document_id";
+pub(super) const CONTENT_KEY: &str = "content";
+pub(super) const METADATA_KEY: &str = "metadata";
+pub(super) fn point_id(session_id: &str, document_id: &str) -> u64 {
+    let ns = Uuid::NAMESPACE_DNS;
+    let key = format!("{session_id}:{document_id}");
+    let uuid = Uuid::new_v5(&ns, key.as_bytes());
+    let bytes = uuid.as_bytes();
+    u64::from_be_bytes([
+        bytes[0], bytes[1], bytes[2], bytes[3],
+        bytes[4], bytes[5], bytes[6], bytes[7],
+    ])
+}
+
+pub(super) fn document_payload(
+    session_id: &str,
+    document: &RagDocument,
+) -> AiResult<Payload> {
+    Payload::try_from(json!({
+        SESSION_ID_KEY: session_id,
+        DOCUMENT_ID_KEY: document.id,
+        CONTENT_KEY: document.content,
+        METADATA_KEY: document.metadata,
+    }))
+    .map_err(|error| AiError::Config(error.to_string()))
+}
+
+pub(super) fn hit_from_scored_point(point: ScoredPoint) -> RagSearchHit {
+    let id = point_id_to_string(point.id);
+    let mut payload = qdrant_payload_to_json(point.payload);
+    let session_id = take_string(&mut payload, SESSION_ID_KEY);
+    let document_id = take_string(&mut payload, DOCUMENT_ID_KEY);
+    let content = take_string(&mut payload, CONTENT_KEY);
+    let metadata = payload
+        .remove(METADATA_KEY)
+        .and_then(|value| match value {
+            Value::Object(object) => Some(object.into_iter().collect()),
+            _ => None,
+        })
+        .unwrap_or_default();
+
+    RagSearchHit {
+        id: if document_id.is_empty() {
+            id
+        } else {
+            document_id
+        },
+        session_id,
+        score: point.score,
+        content,
+        metadata,
+    }
+}
+
+fn point_id_to_string(id: Option<PointId>) -> String {
+    match id.and_then(|id| id.point_id_options) {
+        Some(PointIdOptions::Num(id)) => id.to_string(),
+        Some(PointIdOptions::Uuid(id)) => id,
+        None => String::new(),
+    }
+}
+
+fn qdrant_payload_to_json(
+    payload: HashMap<String, qdrant_client::qdrant::Value>,
+) -> Map<String, Value> {
+    payload
+        .into_iter()
+        .map(|(key, value)| (key, value_to_json(value)))
+        .collect()
+}
+
+fn value_to_json(value: qdrant_client::qdrant::Value) -> Value {
+    match value.kind {
+        Some(Kind::NullValue(_)) | None => Value::Null,
+        Some(Kind::DoubleValue(value)) => json!(value),
+        Some(Kind::IntegerValue(value)) => json!(value),
+        Some(Kind::StringValue(value)) => json!(value),
+        Some(Kind::BoolValue(value)) => json!(value),
+        Some(Kind::StructValue(value)) => Value::Object(
+            value
+                .fields
+                .into_iter()
+                .map(|(key, value)| (key, value_to_json(value)))
+                .collect(),
+        ),
+        Some(Kind::ListValue(value)) => {
+            Value::Array(value.values.into_iter().map(value_to_json).collect())
+        }
+    }
+}
+
+fn take_string(payload: &mut Map<String, Value>, key: &str) -> String {
+    payload
+        .remove(key)
+        .and_then(|value| value.as_str().map(ToOwned::to_owned))
+        .unwrap_or_default()
+}
diff --git a/lib/ai/rag/search.rs b/lib/ai/rag/search.rs
new file mode 100644
index 0000000..95fcd90
--- /dev/null
+++ b/lib/ai/rag/search.rs
@@ -0,0 +1,16 @@
+#[derive(Clone, Debug)]
+pub struct RagSearchOptions {
+    pub limit: u64,
+    pub exact: bool,
+}
+
+impl RagSearchOptions {
+    pub fn new(limit: u64) -> Self {
+        Self { limit, exact: true }
+    }
+
+    pub fn with_exact(mut self, exact: bool) -> Self {
+        self.exact = exact;
+        self
+    }
+}
diff --git a/lib/ai/rag/session.rs b/lib/ai/rag/session.rs
new file mode 100644
index 0000000..f049b88
--- /dev/null
+++ b/lib/ai/rag/session.rs
@@ -0,0 +1,15 @@
+use qdrant_client::qdrant::{Condition, Filter};
+
+use super::payload::SESSION_ID_KEY;
+use crate::error::{AiError, AiResult};
+
+pub(super) fn validate_session_id(session_id: &str) -> AiResult<()> {
+    if session_id.trim().is_empty() {
+        return Err(AiError::Config("rag session_id is required".to_string()));
+    }
+    Ok(())
+}
+
+pub(super) fn session_filter(session_id: &str) -> Filter {
+    Filter::all([Condition::matches(SESSION_ID_KEY, session_id.to_string())])
+}
diff --git a/lib/ai/sync.rs b/lib/ai/sync.rs
new file mode 100644
index 0000000..4f7dae5
--- /dev/null
+++ b/lib/ai/sync.rs
@@ -0,0 +1,126 @@
+use std::error::Error;
+use std::sync::LazyLock;
+
+use tracing::{debug, warn};
+
+use crate::{
+    client::EndpointConfig,
+    error::{AiError, AiResult},
+};
+#[derive(Debug, serde::Deserialize)]
+struct ModelsListResponse {
+    data: Vec<UpstreamModel>,
+}
+#[derive(Debug, Clone, serde::Deserialize)]
+pub struct UpstreamModel {
+    pub id: String,
+    #[serde(default)]
+    pub name: Option<String>,
+    #[serde(default)]
+    pub owned_by: Option<String>,
+    #[serde(default)]
+    pub context_length: Option<i32>,
+    #[serde(default)]
+    pub max_output_tokens: Option<i32>,
+    #[serde(default)]
+    pub capabilities: Option<UpstreamCapabilities>,
+    #[serde(default)]
+    pub pricing: Option<UpstreamPricing>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize)]
+pub struct UpstreamCapabilities {
+    #[serde(default)]
+    pub vision: Option<bool>,
+    #[serde(default)]
+    pub tool_call: Option<bool>,
+    #[serde(default)]
+    pub reasoning: Option<bool>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize)]
+pub struct UpstreamPricing {
+    #[serde(default)]
+    pub prompt: Option<String>,
+    #[serde(default)]
+    pub completion: Option<String>,
+    #[serde(default)]
+    pub input: Option<f64>,
+    #[serde(default)]
+    pub output: Option<f64>,
+    #[serde(default)]
+    pub cache_read: Option<f64>,
+    #[serde(default)]
+    pub unit: Option<String>,
+    #[serde(default)]
+    pub currency: Option<String>,
+}
+static HTTP_CLIENT: LazyLock<reqwest::Client> = LazyLock::new(|| {
+    let mut builder = reqwest::Client::builder();
+    let proxy_url = std::env::var("HTTPS_PROXY")
+        .or_else(|_| std::env::var("https_proxy"))
+        .or_else(|_| std::env::var("HTTP_PROXY"))
+        .or_else(|_| std::env::var("http_proxy"))
+        .ok();
+    if let Some(raw) = &proxy_url {
+        let url = raw.trim().trim_matches('"').trim_matches('\'');
+        match reqwest::Proxy::all(url) {
+            Ok(proxy) => {
+                debug!(proxy_url = %url, "sync: using proxy");
+                builder = builder.proxy(proxy);
+            }
+            Err(e) => {
+                warn!(proxy_url = %url, error = %e, "sync: invalid proxy URL, skipping");
+            }
+        }
+    }
+    #[allow(clippy::expect_used)]
+    builder.build().expect("failed to build reqwest HTTP client — check system TLS configuration")
+});
+pub async fn list_models(
+    config: &EndpointConfig,
+) -> AiResult<Vec<UpstreamModel>> {
+    let base = config.base_url.trim_end_matches('/');
+    let url = if base.ends_with("/v1") {
+        format!("{}/models", base)
+    } else {
+        format!("{}/v1/models", base)
+    };
+
+    debug!(url = %url, "listing models from upstream");
+    let resp = HTTP_CLIENT
+        .get(&url)
+        .header("Authorization", format!("Bearer {}", config.api_key.trim()))
+        .send()
+        .await
+        .map_err(|e| {
+            tracing::error!(
+                error = %e,
+                source = ?e.source(),
+                "list_models: request failed with full cause chain"
+            );
+            AiError::Response(format!("failed to list models: {}", e))
+        })?;
+
+    let body = resp
+        .text()
+        .await
+        .map_err(|e| AiError::Response(format!("failed to read models body: {}", e)))?;
+    if let Ok(parsed) = serde_json::from_str::<ModelsListResponse>(&body) {
+        debug!(count = parsed.data.len(), "parsed models in standard format");
+        return Ok(parsed.data);
+    }
+    if let Ok(parsed) = serde_json::from_str::<Vec<UpstreamModel>>(&body) {
+        debug!(count = parsed.len(), "parsed models in array format");
+        return Ok(parsed);
+    }
+
+    warn!(
+        body = %body.chars().take(500).collect::<String>(),
+        "list_models: unknown response format"
+    );
+    Err(AiError::Response(format!(
+        "unexpected /v1/models response format (first 200 chars): {}",
+        body.chars().take(200).collect::<String>()
+    )))
+}
diff --git a/lib/ai/tool/mod.rs b/lib/ai/tool/mod.rs
new file mode 100644
index 0000000..379b9e7
--- /dev/null
+++ b/lib/ai/tool/mod.rs
@@ -0,0 +1,5 @@
+pub mod register;
+pub mod tools;
+pub mod toolset;
+
+pub use toolset::{Toolset, ToolsetRegistry, toolset_names};
diff --git a/lib/ai/tool/register.rs b/lib/ai/tool/register.rs
new file mode 100644
index 0000000..1c7d812
--- /dev/null
+++ b/lib/ai/tool/register.rs
@@ -0,0 +1,65 @@
+use crate::tool::tools::FunctionCall;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+#[derive(Clone)]
+pub struct ToolRegister<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    pub tools: Vec<Arc<dyn FunctionCall<Context = C>>>,
+    index: HashMap<String, usize>,
+}
+
+impl<C> ToolRegister<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    pub fn new() -> Self {
+        ToolRegister {
+            tools: Vec::new(),
+            index: HashMap::new(),
+        }
+    }
+
+    pub fn register<T>(&mut self, tool: T)
+    where
+        T: FunctionCall<Context = C> + 'static,
+    {
+        let idx = self.tools.len();
+        self.index.insert(tool.name().to_string(), idx);
+        self.tools.push(Arc::new(tool));
+    }
+
+    pub fn with_tool<T>(mut self, tool: T) -> Self
+    where
+        T: FunctionCall<Context = C> + 'static,
+    {
+        self.register(tool);
+        self
+    }
+
+    pub fn get(
+        &self,
+        name: &str,
+    ) -> Option<Arc<dyn FunctionCall<Context = C>>> {
+        self.index.get(name).map(|&idx| self.tools[idx].clone())
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.tools.is_empty()
+    }
+
+    pub fn len(&self) -> usize {
+        self.tools.len()
+    }
+}
+
+impl<C> Default for ToolRegister<C>
+where
+    C: Clone + Send + Sync + 'static,
+{
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/lib/ai/tool/tools.rs b/lib/ai/tool/tools.rs
new file mode 100644
index 0000000..be630f2
--- /dev/null
+++ b/lib/ai/tool/tools.rs
@@ -0,0 +1,18 @@
+use crate::error::AiResult;
+use async_trait::async_trait;
+use serde_json::Value;
+
+#[async_trait]
+pub trait FunctionCall: Send + Sync {
+    type Context;
+    fn name(&self) -> &'static str;
+    fn description(&self) -> &'static str {
+        ""
+    }
+    fn schema(&self) -> Value;
+    async fn call(
+        &self,
+        context: &mut Self::Context,
+        args: Value,
+    ) -> AiResult<Value>;
+}
diff --git a/lib/ai/tool/toolset.rs b/lib/ai/tool/toolset.rs
new file mode 100644
index 0000000..7e9da8e
--- /dev/null
+++ b/lib/ai/tool/toolset.rs
@@ -0,0 +1,146 @@
+use std::collections::{HashMap, HashSet};
+
+use serde::{Deserialize, Serialize};
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct Toolset {
+    pub name: String,
+    pub description: String,
+    pub tools: Vec<String>,
+    pub requires_env: Vec<String>,
+}
+
+impl Toolset {
+    pub fn new(
+        name: impl Into<String>,
+        description: impl Into<String>,
+    ) -> Self {
+        Self {
+            name: name.into(),
+            description: description.into(),
+            tools: Vec::new(),
+            requires_env: Vec::new(),
+        }
+    }
+
+    pub fn with_tool(mut self, tool_name: impl Into<String>) -> Self {
+        self.tools.push(tool_name.into());
+        self
+    }
+
+    pub fn with_tools(mut self, tool_names: impl IntoIterator<Item = impl Into<String>>) -> Self {
+        self.tools.extend(tool_names.into_iter().map(Into::into));
+        self
+    }
+
+    pub fn with_required_env(
+        mut self,
+        env_vars: impl IntoIterator<Item = impl Into<String>>,
+    ) -> Self {
+        self.requires_env.extend(env_vars.into_iter().map(Into::into));
+        self
+    }
+    pub fn is_available(&self) -> bool {
+        for env_var in &self.requires_env {
+            if std::env::var(env_var).is_err() {
+                return false;
+            }
+        }
+        true
+    }
+
+    pub fn contains(&self, tool_name: &str) -> bool {
+        self.tools.iter().any(|t| t == tool_name)
+    }
+}
+pub mod toolset_names {
+    pub const CORE: &str = "core";
+    pub const TERMINAL: &str = "terminal";
+    pub const WEB: &str = "web";
+    pub const FILE: &str = "file";
+    pub const MEMORY: &str = "memory";
+    pub const VISION: &str = "vision";
+    pub const SEARCH: &str = "search";
+    pub const BROWSER: &str = "browser";
+    pub const CODE_EXECUTION: &str = "code_execution";
+    pub const DELEGATION: &str = "delegation";
+}
+#[derive(Clone, Debug, Default)]
+pub struct ToolsetRegistry {
+    toolsets: HashMap<String, Toolset>,
+    tool_index: HashMap<String, String>,
+}
+
+impl ToolsetRegistry {
+    pub fn new() -> Self {
+        Self::default()
+    }
+    pub fn register(&mut self, toolset: Toolset) {
+        let name = toolset.name.clone();
+        for tool in &toolset.tools {
+            self.tool_index.insert(tool.clone(), name.clone());
+        }
+        self.toolsets.insert(name, toolset);
+    }
+
+    pub fn get(&self, name: &str) -> Option<&Toolset> {
+        self.toolsets.get(name)
+    }
+    pub fn toolset_for(&self, tool_name: &str) -> Option<&str> {
+        self.tool_index.get(tool_name).map(String::as_str)
+    }
+    pub fn resolve_tool_names(
+        &self,
+        enabled: &[String],
+        disabled: &[String],
+        default_all: bool,
+    ) -> Vec<String> {
+        let mut names = HashSet::new();
+        let mut denied = HashSet::new();
+
+        for ts_name in disabled {
+            if let Some(ts) = self.toolsets.get(ts_name) {
+                for tool in &ts.tools {
+                    denied.insert(tool.clone());
+                }
+            }
+        }
+
+        if enabled.is_empty() && default_all {
+            for ts in self.toolsets.values() {
+                if !disabled.contains(&ts.name) && ts.is_available() {
+                    for tool in &ts.tools {
+                        if !denied.contains(tool) {
+                            names.insert(tool.clone());
+                        }
+                    }
+                }
+            }
+        } else {
+            for ts_name in enabled {
+                if let Some(ts) = self.toolsets.get(ts_name) {
+                    if ts.is_available() {
+                        for tool in &ts.tools {
+                            if !denied.contains(tool) {
+                                names.insert(tool.clone());
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        let mut sorted: Vec<String> = names.into_iter().collect();
+        sorted.sort();
+        sorted
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = &Toolset> {
+        self.toolsets.values()
+    }
+
+    pub fn all_tool_names(&self) -> Vec<String> {
+        let mut names: Vec<String> = self.tool_index.keys().cloned().collect();
+        names.sort();
+        names
+    }
+}
diff --git a/lib/api/Cargo.toml b/lib/api/Cargo.toml
new file mode 100644
index 0000000..a507a27
--- /dev/null
+++ b/lib/api/Cargo.toml
@@ -0,0 +1,44 @@
+[package]
+name = "api"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "src/lib.rs"
+name = "api"
+
+[dependencies]
+service = { workspace = true }
+session = { workspace = true }
+config = { workspace = true }
+db = { workspace = true }
+model = { workspace = true }
+git = { workspace = true }
+channel = { workspace = true }
+socketio = { workspace = true }
+
+actix-web = { workspace = true }
+actix-ws = { workspace = true }
+utoipa = { workspace = true, features = ["chrono", "uuid", "actix_extras"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+uuid = { workspace = true, features = ["v4", "v7", "serde"] }
+chrono = { workspace = true }
+async-stream = { workspace = true }
+tokio-stream = { workspace = true }
+base64 = { workspace = true }
+comrak = { workspace = true }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp"] }
+storage = { workspace = true }
+
+[lints]
+workspace = true
diff --git a/lib/api/src/agent/conversation.rs b/lib/api/src/agent/conversation.rs
new file mode 100644
index 0000000..1663a77
--- /dev/null
+++ b/lib/api/src/agent/conversation.rs
@@ -0,0 +1,296 @@
+use actix_web::{HttpResponse, web, web::ServiceConfig};
+use service::AppService;
+use service::agent::conversation::{
+    ConversationResponse, ConversationWithSessionResponse, CreateConversation, MessageResponse, UpdateConversation,
+};
+use service::agent::types::{AgentRunRequest, AgentRunResponse};
+use session::Session;
+use tokio_stream::StreamExt;
+use tokio_stream::wrappers::UnboundedReceiverStream;
+use uuid::Uuid;
+
+use crate::error::{ApiError, ok_json};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("/sessions/{session_id}/conversations")
+            .route(web::get().to(list_conversations))
+            .route(web::post().to(create_conversation)),
+    )
+    .service(
+        web::resource("/conversations")
+            .route(web::get().to(list_all_conversations)),
+    )
+    .service(
+        web::resource("/conversations/{id}")
+            .route(web::get().to(get_conversation))
+            .route(web::patch().to(update_conversation))
+            .route(web::delete().to(delete_conversation)),
+    )
+    .service(
+        web::resource("/conversations/{id}/messages")
+            .route(web::get().to(list_messages))
+            .route(web::post().to(send_message)),
+    )
+    .service(
+        web::resource("/conversations/{id}/stream")
+            .route(web::post().to(stream_agent)),
+    )
+    .service(
+        web::resource("/conversations/{id}/fork")
+            .route(web::post().to(fork_conversation)),
+    );
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/agent/sessions/{session_id}/conversations",
+    params(("session_id" = Uuid, Path)),
+    responses((status = 200, body = Vec<ConversationResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_conversations(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_conversation_list(user_id, path.into_inner()).await?)
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/agent/sessions/{session_id}/conversations",
+    params(("session_id" = Uuid, Path)),
+    request_body = CreateConversation,
+    responses((status = 200, body = ConversationResponse)),
+    security(("session" = []))
+)]
+pub async fn create_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<CreateConversation>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_conversation_create(user_id, path.into_inner(), body.into_inner())
+            .await?,
+    )
+}
+
+#[derive(Debug, serde::Deserialize, utoipa::IntoParams)]
+pub struct ListAllConversationsQuery {
+    pub wk: Option<String>,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/agent/conversations",
+    params(("wk" = Option<String>, Query, description = "Filter by workspace name")),
+    responses((status = 200, body = Vec<ConversationWithSessionResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_all_conversations(
+    session: Session,
+    service: web::Data<AppService>,
+    query: web::Query<ListAllConversationsQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_conversation_list_all(user_id, query.wk.as_deref())
+            .await?,
+    )
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/agent/conversations/{id}",
+    params(("id" = Uuid, Path)),
+    responses((status = 200, body = ConversationResponse)),
+    security(("session" = []))
+)]
+pub async fn get_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_conversation_get(user_id, path.into_inner()).await?)
+}
+
+#[utoipa::path(
+    patch, path = "/api/v1/agent/conversations/{id}",
+    params(("id" = Uuid, Path)),
+    request_body = UpdateConversation,
+    responses((status = 200, body = ConversationResponse)),
+    security(("session" = []))
+)]
+pub async fn update_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<UpdateConversation>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_conversation_update(user_id, path.into_inner(), body.into_inner())
+            .await?,
+    )
+}
+
+#[utoipa::path(
+    delete, path = "/api/v1/agent/conversations/{id}",
+    params(("id" = Uuid, Path)),
+    responses((status = 200)),
+    security(("session" = []))
+)]
+pub async fn delete_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    service.agent_conversation_delete(user_id, path.into_inner()).await?;
+    Ok(HttpResponse::Ok().json(serde_json::json!({ "deleted": true })))
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/agent/conversations/{id}/archive",
+    params(("id" = Uuid, Path)),
+    responses((status = 200, body = ConversationResponse)),
+    security(("session" = []))
+)]
+pub async fn archive_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_conversation_archive(user_id, path.into_inner()).await?)
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/agent/conversations/{id}/unarchive",
+    params(("id" = Uuid, Path)),
+    responses((status = 200, body = ConversationResponse)),
+    security(("session" = []))
+)]
+pub async fn unarchive_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_conversation_unarchive(user_id, path.into_inner()).await?)
+}
+#[utoipa::path(
+    get, path = "/api/v1/agent/conversations/{id}/messages",
+    params(("id" = Uuid, Path), ("before" = Option<Uuid>, Query), ("limit" = Option<u32>, Query)),
+    responses((status = 200, body = Vec<MessageResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_messages(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    query: web::Query<MessageListQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_message_list(user_id, path.into_inner(), query.limit, query.before)
+            .await?,
+    )
+}
+
+#[derive(Debug, serde::Deserialize, utoipa::IntoParams)]
+pub struct MessageListQuery {
+    pub limit: Option<u32>,
+    pub before: Option<Uuid>,
+}
+#[utoipa::path(
+    post, path = "/api/v1/agent/conversations/{id}/messages",
+    params(("id" = Uuid, Path)),
+    request_body = AgentRunRequest,
+    responses((status = 200, body = AgentRunResponse)),
+    security(("session" = []))
+)]
+pub async fn send_message(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<AgentRunRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    let conversation_id = path.into_inner();
+    let mut req = body.into_inner();
+    req.conversation_id = Some(conversation_id);
+    ok_json(service.agent_run(user_id, req).await?)
+}
+#[utoipa::path(
+    post, path = "/api/v1/agent/conversations/{id}/stream",
+    params(("id" = Uuid, Path)),
+    request_body = AgentRunRequest,
+    responses((status = 200, description = "SSE stream")),
+    security(("session" = []))
+)]
+pub async fn stream_agent(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<AgentRunRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    let conversation_id = path.into_inner();
+    let mut req = body.into_inner();
+    req.conversation_id = Some(conversation_id);
+
+    let rx = service.agent_run_streaming(user_id, req).await?;
+
+    let stream = UnboundedReceiverStream::new(rx).map(|payload| {
+        let frame = if payload.starts_with("data:") {
+            payload
+        } else {
+            format!("data: {}\n\n", payload)
+        };
+        Ok::<_, actix_web::Error>(actix_web::web::Bytes::from(frame))
+    });
+
+    Ok(HttpResponse::Ok()
+        .content_type("text/event-stream")
+        .insert_header(("Cache-Control", "no-cache"))
+        .insert_header(("Connection", "keep-alive"))
+        .insert_header(("X-Accel-Buffering", "no"))
+        .streaming(stream))
+}
+
+#[derive(Debug, serde::Deserialize, utoipa::ToSchema)]
+pub struct ForkConversationRequest {
+    pub message_id: Option<Uuid>,
+    pub title: Option<String>,
+}
+#[utoipa::path(
+    post, path = "/api/v1/agent/conversations/{id}/fork",
+    params(("id" = Uuid, Path)),
+    request_body = ForkConversationRequest,
+    responses((status = 200, body = ConversationResponse)),
+    security(("session" = []))
+)]
+pub async fn fork_conversation(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<ForkConversationRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_conversation_fork(
+                user_id,
+                path.into_inner(),
+                body.message_id,
+                body.title.as_deref(),
+            )
+            .await?,
+    )
+}
diff --git a/lib/api/src/agent/mod.rs b/lib/api/src/agent/mod.rs
new file mode 100644
index 0000000..3c47877
--- /dev/null
+++ b/lib/api/src/agent/mod.rs
@@ -0,0 +1,12 @@
+pub mod conversation;
+pub mod session;
+
+use actix_web::{web, web::ServiceConfig};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::scope("/agent")
+            .configure(session::configure)
+            .configure(conversation::configure),
+    );
+}
diff --git a/lib/api/src/agent/session.rs b/lib/api/src/agent/session.rs
new file mode 100644
index 0000000..db67e26
--- /dev/null
+++ b/lib/api/src/agent/session.rs
@@ -0,0 +1,162 @@
+use actix_web::{HttpResponse, web, web::ServiceConfig};
+use service::AppService;
+use service::agent::session::{
+    AgentSessionResponse, CreateAgentSession, UpdateAgentSession,
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::{ApiError, ok_json};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("/sessions")
+            .route(web::get().to(list_sessions))
+            .route(web::post().to(create_session)),
+    )
+    .service(
+        web::resource("/sessions/search")
+            .route(web::get().to(search_sessions)),
+    )
+    .service(
+        web::resource("/sessions/{id}")
+            .route(web::get().to(get_session))
+            .route(web::patch().to(update_session))
+            .route(web::delete().to(delete_session)),
+    )
+    .service(
+        web::resource("/sessions/{id}/toolsets")
+            .route(web::patch().to(update_session_toolsets)),
+    );
+}
+#[utoipa::path(
+    get, path = "/api/v1/agent/sessions",
+    responses((status = 200, body = Vec<AgentSessionResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_sessions(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_session_list(user_id).await?)
+}
+#[utoipa::path(
+    post, path = "/api/v1/agent/sessions",
+    request_body = CreateAgentSession,
+    responses((status = 200, body = AgentSessionResponse)),
+    security(("session" = []))
+)]
+pub async fn create_session(
+    session: Session,
+    service: web::Data<AppService>,
+    body: web::Json<CreateAgentSession>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_session_create(user_id, body.into_inner()).await?)
+}
+#[utoipa::path(
+    get, path = "/api/v1/agent/sessions/{id}",
+    params(("id" = Uuid, Path)),
+    responses((status = 200, body = AgentSessionResponse)),
+    security(("session" = []))
+)]
+pub async fn get_session(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_session_get(user_id, path.into_inner()).await?)
+}
+#[utoipa::path(
+    patch, path = "/api/v1/agent/sessions/{id}",
+    params(("id" = Uuid, Path)),
+    request_body = UpdateAgentSession,
+    responses((status = 200, body = AgentSessionResponse)),
+    security(("session" = []))
+)]
+pub async fn update_session(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<UpdateAgentSession>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.agent_session_update(user_id, path.into_inner(), body.into_inner()).await?)
+}
+#[utoipa::path(
+    delete, path = "/api/v1/agent/sessions/{id}",
+    params(("id" = Uuid, Path)),
+    responses((status = 200)),
+    security(("session" = []))
+)]
+pub async fn delete_session(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    service.agent_session_delete(user_id, path.into_inner()).await?;
+    Ok(HttpResponse::Ok().json(serde_json::json!({ "deleted": true })))
+}
+
+#[derive(Debug, serde::Deserialize, utoipa::IntoParams)]
+pub struct SearchQuery {
+    pub q: String,
+    #[serde(default = "default_limit")]
+    pub limit: u32,
+}
+
+const fn default_limit() -> u32 {
+    20
+}
+#[utoipa::path(
+    get, path = "/api/v1/agent/sessions/search",
+    params(("q" = String, Query), ("limit" = Option<u32>, Query)),
+    responses((status = 200, body = Vec<AgentSessionResponse>)),
+    security(("session" = []))
+)]
+pub async fn search_sessions(
+    session: Session,
+    service: web::Data<AppService>,
+    query: web::Query<SearchQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_session_search(user_id, &query.q, query.limit)
+            .await?,
+    )
+}
+
+#[derive(Debug, serde::Deserialize, utoipa::ToSchema)]
+pub struct UpdateToolsetsRequest {
+    pub enabled: Option<Vec<String>>,
+    pub disabled: Option<Vec<String>>,
+}
+#[utoipa::path(
+    patch, path = "/api/v1/agent/sessions/{id}/toolsets",
+    params(("id" = Uuid, Path)),
+    request_body = UpdateToolsetsRequest,
+    responses((status = 200, body = AgentSessionResponse)),
+    security(("session" = []))
+)]
+pub async fn update_session_toolsets(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<Uuid>,
+    body: web::Json<UpdateToolsetsRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(
+        service
+            .agent_session_update_toolsets(
+                user_id,
+                path.into_inner(),
+                body.enabled.clone(),
+                body.disabled.clone(),
+            )
+            .await?,
+    )
+}
diff --git a/lib/api/src/ai/mod.rs b/lib/api/src/ai/mod.rs
new file mode 100644
index 0000000..09d0a59
--- /dev/null
+++ b/lib/api/src/ai/mod.rs
@@ -0,0 +1,47 @@
+pub mod model;
+pub mod provider;
+
+use actix_web::web;
+use actix_web::web::ServiceConfig;
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::scope("/ai")
+            .service(
+                web::resource("/providers")
+                    .route(web::get().to(provider::list_providers)),
+            )
+            .service(
+                web::resource("/providers/{id}")
+                    .route(web::get().to(provider::get_provider)),
+            )
+            .service(
+                web::resource("/models")
+                    .route(web::get().to(model::list_models)),
+            )
+            .service(
+                web::resource("/models/{id}")
+                    .route(web::get().to(model::get_model)),
+            )
+            .service(
+                web::resource("/models/{id}/versions")
+                    .route(web::get().to(model::list_versions)),
+            )
+            .service(
+                web::resource("/models/{id}/card")
+                    .route(web::get().to(model::get_card)),
+            )
+            .service(
+                web::resource("/models/{id}/tags")
+                    .route(web::get().to(model::list_tags)),
+            )
+            .service(
+                web::resource("/models/{id}/discussions")
+                    .route(web::get().to(model::list_discussions)),
+            )
+            .service(
+                web::resource("/models/{id}/likes")
+                    .route(web::get().to(model::list_likes)),
+            ),
+    );
+}
diff --git a/lib/api/src/ai/model.rs b/lib/api/src/ai/model.rs
new file mode 100644
index 0000000..d75bfa1
--- /dev/null
+++ b/lib/api/src/ai/model.rs
@@ -0,0 +1,139 @@
+use crate::error::{ApiError, ok_json};
+use actix_web::{HttpResponse, web};
+use serde::Deserialize;
+use service::AppService;
+use service::Pagination;
+use service::ai::types::{
+    AiDiscussionResponse, AiLikeResponse, AiModelCardResponse, AiModelFilter,
+    AiModelListItem, AiModelResponse, AiModelVersionResponse,
+};
+use session::Session;
+use uuid::Uuid;
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ModelIdPath {
+    pub id: Uuid,
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models",
+    params(AiModelFilter, Pagination),
+    responses((status = 200, body = Vec<AiModelListItem>), (status = 401, description = "Unauthorized")),
+    security(("session" = []))
+)]
+pub async fn list_models(
+    session: Session,
+    service: web::Data<AppService>,
+    filter: web::Query<AiModelFilter>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_model_list(
+                &session,
+                filter.into_inner(),
+                pagination.into_inner(),
+            )
+            .await?,
+    )
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models/{id}",
+    params(("id" = String, Path)), responses((status = 200, body = AiModelResponse),
+        (status = 401, description = "Unauthorized"), (status = 404, description = "Not found")),
+    security(("session" = []))
+)]
+pub async fn get_model(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ModelIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(service.ai_model_get(&session, path.into_inner().id).await?)
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models/{id}/versions",
+    params(("id" = String, Path)), responses((status = 200, body = Vec<AiModelVersionResponse>),
+        (status = 401, description = "Unauthorized")),
+    security(("session" = []))
+)]
+pub async fn list_versions(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ModelIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_model_versions(&session, path.into_inner().id)
+            .await?,
+    )
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models/{id}/card",
+    params(("id" = String, Path)), responses((status = 200, body = Option<AiModelCardResponse>),
+        (status = 401, description = "Unauthorized")),
+    security(("session" = []))
+)]
+pub async fn get_card(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ModelIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_model_card(&session, path.into_inner().id)
+            .await?,
+    )
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models/{id}/tags",
+    params(("id" = String, Path)), responses((status = 200, body = Vec<String>)),
+    security(("session" = []))
+)]
+pub async fn list_tags(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ModelIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_model_tags(&session, path.into_inner().id)
+            .await?,
+    )
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models/{id}/discussions",
+    params(("id" = String, Path), Pagination),
+    responses((status = 200, body = Vec<AiDiscussionResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_discussions(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ModelIdPath>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_model_discussions(
+                &session,
+                path.into_inner().id,
+                pagination.into_inner(),
+            )
+            .await?,
+    )
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/models/{id}/likes",
+    params(("id" = String, Path)), responses((status = 200, body = Vec<AiLikeResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_likes(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ModelIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_model_likes(&session, path.into_inner().id)
+            .await?,
+    )
+}
diff --git a/lib/api/src/ai/provider.rs b/lib/api/src/ai/provider.rs
new file mode 100644
index 0000000..98a3e48
--- /dev/null
+++ b/lib/api/src/ai/provider.rs
@@ -0,0 +1,39 @@
+use crate::error::{ApiError, ok_json};
+use actix_web::{HttpResponse, web};
+use serde::Deserialize;
+use service::AppService;
+use service::ai::types::AiProviderResponse;
+use session::Session;
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ProviderIdPath {
+    pub id: uuid::Uuid,
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/providers",
+    responses((status = 200, body = Vec<AiProviderResponse>), (status = 401, description = "Unauthorized")),
+    security(("session" = []))
+)]
+pub async fn list_providers(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(service.ai_provider_list(&session).await?)
+}
+#[utoipa::path(
+    get, path = "/api/v1/ai/providers/{id}",
+    params(("id" = String, Path)), responses((status = 200, body = AiProviderResponse),
+        (status = 401, description = "Unauthorized"), (status = 404, description = "Not found")),
+    security(("session" = []))
+)]
+pub async fn get_provider(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ProviderIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(
+        service
+            .ai_provider_get(&session, path.into_inner().id)
+            .await?,
+    )
+}
diff --git a/lib/api/src/auth/captcha.rs b/lib/api/src/auth/captcha.rs
new file mode 100644
index 0000000..d80fd44
--- /dev/null
+++ b/lib/api/src/auth/captcha.rs
@@ -0,0 +1,29 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    auth::captcha::{CaptchaQuery, CaptchaResponse},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/auth/captcha",
+    params(CaptchaQuery),
+    responses((status = 200, body = CaptchaResponse)),
+    tag = "auth"
+)]
+pub async fn captcha(
+    session: Session,
+    query: web::Query<CaptchaQuery>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_captcha(&session, query.into_inner()).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/auth/email.rs b/lib/api/src/auth/email.rs
new file mode 100644
index 0000000..3850714
--- /dev/null
+++ b/lib/api/src/auth/email.rs
@@ -0,0 +1,64 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    auth::email::{EmailChangeRequest, EmailResponse, EmailVerifyRequest},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/auth/email",
+    responses((status = 200, body = EmailResponse)),
+    tag = "auth"
+)]
+pub async fn get_email(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_get_email(&session).await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/email",
+    request_body = EmailChangeRequest,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn email_change_request(
+    session: Session,
+    params: web::Json<EmailChangeRequest>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .auth_email_change_request(&session, params.into_inner())
+        .await?;
+    ok()
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/email/verify",
+    request_body = EmailVerifyRequest,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn email_verify(
+    params: web::Json<EmailVerifyRequest>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service.auth_email_verify(params.into_inner()).await?;
+    ok()
+}
diff --git a/lib/api/src/auth/login.rs b/lib/api/src/auth/login.rs
new file mode 100644
index 0000000..2b48e70
--- /dev/null
+++ b/lib/api/src/auth/login.rs
@@ -0,0 +1,25 @@
+use actix_web::{HttpResponse, web};
+use service::{AppService, auth::login::LoginParams};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/login",
+    request_body = LoginParams,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn login(
+    session: Session,
+    params: web::Json<LoginParams>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service.auth_login(params.into_inner(), session).await?;
+    ok()
+}
diff --git a/lib/api/src/auth/logout.rs b/lib/api/src/auth/logout.rs
new file mode 100644
index 0000000..2e519a2
--- /dev/null
+++ b/lib/api/src/auth/logout.rs
@@ -0,0 +1,23 @@
+use actix_web::{HttpResponse, web};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/logout",
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn logout(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service.auth_logout(&session).await?;
+    ok()
+}
diff --git a/lib/api/src/auth/me.rs b/lib/api/src/auth/me.rs
new file mode 100644
index 0000000..9e40beb
--- /dev/null
+++ b/lib/api/src/auth/me.rs
@@ -0,0 +1,24 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, auth::me::ContextMe};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/auth/me",
+    responses((status = 200, body = ContextMe)),
+    tag = "auth"
+)]
+pub async fn me(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_me(session).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/auth/mod.rs b/lib/api/src/auth/mod.rs
new file mode 100644
index 0000000..7067c69
--- /dev/null
+++ b/lib/api/src/auth/mod.rs
@@ -0,0 +1,75 @@
+pub mod captcha;
+pub mod email;
+pub mod login;
+pub mod logout;
+pub mod me;
+pub mod register;
+pub mod reset_pass;
+pub mod rsa;
+pub mod totp;
+
+use actix_web::{web, web::ServiceConfig};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::scope("/auth")
+            .service(
+                web::resource("/captcha")
+                    .route(web::get().to(captcha::captcha)),
+            )
+            .service(
+                web::resource("/login").route(web::post().to(login::login)),
+            )
+            .service(
+                web::resource("/logout").route(web::post().to(logout::logout)),
+            )
+            .service(web::resource("/me").route(web::get().to(me::me)))
+            .service(
+                web::resource("/register")
+                    .route(web::post().to(register::register)),
+            )
+            .service(
+                web::scope("/reset-password")
+                    .service(web::resource("/request").route(
+                        web::post().to(reset_pass::reset_password_request),
+                    ))
+                    .service(web::resource("/verify").route(
+                        web::post().to(reset_pass::reset_password_verify),
+                    )),
+            )
+            .service(web::resource("/public-key").route(web::get().to(rsa::rsa)))
+            .service(
+                web::scope("/2fa")
+                    .service(
+                        web::resource("/enable")
+                            .route(web::post().to(totp::enable_2fa)),
+                    )
+                    .service(
+                        web::resource("/verify")
+                            .route(web::post().to(totp::verify_2fa)),
+                    )
+                    .service(
+                        web::resource("")
+                            .route(web::get().to(totp::status_2fa))
+                            .route(web::delete().to(totp::disable_2fa)),
+                    )
+                    .service(
+                        web::resource("/backup-codes").route(
+                            web::post().to(totp::regenerate_backup_codes),
+                        ),
+                    ),
+            )
+            .service(
+                web::scope("/email")
+                    .service(
+                        web::resource("")
+                            .route(web::get().to(email::get_email))
+                            .route(web::put().to(email::email_change_request)),
+                    )
+                    .service(
+                        web::resource("/verify")
+                            .route(web::post().to(email::email_verify)),
+                    ),
+            ),
+    );
+}
diff --git a/lib/api/src/auth/register.rs b/lib/api/src/auth/register.rs
new file mode 100644
index 0000000..3918cb5
--- /dev/null
+++ b/lib/api/src/auth/register.rs
@@ -0,0 +1,26 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, auth::register::RegisterParams};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/register",
+    request_body = RegisterParams,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn register(
+    session: Session,
+    params: web::Json<RegisterParams>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_register(params.into_inner(), &session).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/auth/reset_pass.rs b/lib/api/src/auth/reset_pass.rs
new file mode 100644
index 0000000..ed2fe9f
--- /dev/null
+++ b/lib/api/src/auth/reset_pass.rs
@@ -0,0 +1,47 @@
+use actix_web::{HttpResponse, web};
+use service::{
+    AppService,
+    auth::reset_pass::{ResetPasswordRequest, ResetPasswordVerifyParams},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/reset-password/request",
+    request_body = ResetPasswordRequest,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn reset_password_request(
+    params: web::Json<ResetPasswordRequest>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .auth_reset_password_request(params.into_inner())
+        .await?;
+    ok()
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/reset-password/verify",
+    request_body = ResetPasswordVerifyParams,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn reset_password_verify(
+    session: Session,
+    params: web::Json<ResetPasswordVerifyParams>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .auth_reset_password_verify(&session, params.into_inner())
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/auth/rsa.rs b/lib/api/src/auth/rsa.rs
new file mode 100644
index 0000000..66ae85b
--- /dev/null
+++ b/lib/api/src/auth/rsa.rs
@@ -0,0 +1,24 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, auth::rsa::RsaResponse};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/auth/public-key",
+    responses((status = 200, body = RsaResponse)),
+    tag = "auth"
+)]
+pub async fn rsa(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_rsa(&session).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/auth/totp.rs b/lib/api/src/auth/totp.rs
new file mode 100644
index 0000000..c1e81ab
--- /dev/null
+++ b/lib/api/src/auth/totp.rs
@@ -0,0 +1,102 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    auth::totp::{
+        Disable2FAParams, Enable2FAResponse, Get2FAStatusResponse,
+        Verify2FAParams,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/2fa/enable",
+    responses((status = 200, body = Enable2FAResponse)),
+    tag = "auth"
+)]
+pub async fn enable_2fa(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_2fa_enable(&session).await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/2fa/verify",
+    request_body = Verify2FAParams,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn verify_2fa(
+    session: Session,
+    params: web::Json<Verify2FAParams>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .auth_2fa_verify_and_enable(&session, params.into_inner())
+        .await?;
+    ok()
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/auth/2fa",
+    request_body = Disable2FAParams,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn disable_2fa(
+    session: Session,
+    params: web::Json<Disable2FAParams>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .auth_2fa_disable(&session, params.into_inner())
+        .await?;
+    ok()
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/auth/2fa",
+    responses((status = 200, body = Get2FAStatusResponse)),
+    tag = "auth"
+)]
+pub async fn status_2fa(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.auth_2fa_status(&session).await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/2fa/backup-codes",
+    request_body = String,
+    responses((status = 200)),
+    tag = "auth"
+)]
+pub async fn regenerate_backup_codes(
+    session: Session,
+    params: web::Json<String>,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .auth_2fa_regenerate_backup_codes(&session, params.into_inner())
+        .await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/channel/mod.rs b/lib/api/src/channel/mod.rs
new file mode 100644
index 0000000..fb14f87
--- /dev/null
+++ b/lib/api/src/channel/mod.rs
@@ -0,0 +1,207 @@
+pub mod rest;
+pub mod rest_ai;
+pub mod rest_interact;
+pub mod rest_member;
+pub mod rest_message;
+pub mod rest_room;
+pub mod rest_voice;
+pub mod token;
+
+pub use channel::ChannelBus;
+
+use actix_web::web::ServiceConfig;
+
+pub fn configure(cfg: &mut ServiceConfig, bus: ChannelBus) {
+    socketio::configure_at(cfg, "/socket.io", bus.io().clone());
+    socketio::configure_at(cfg, "/socket.io/", bus.io().clone());
+    cfg.service(
+        actix_web::web::resource("/ping")
+            .route(actix_web::web::get().to(rest::ping)),
+    )
+    .service(
+        actix_web::web::resource("/csrf")
+            .route(actix_web::web::get().to(rest::csrf_token)),
+    );
+    cfg.service(
+        actix_web::web::resource("/rooms/{room_id}/messages")
+            .route(actix_web::web::get().to(rest_message::list_messages))
+            .route(actix_web::web::post().to(rest_message::create_message)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/messages/around")
+            .route(actix_web::web::get().to(rest_message::messages_around)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/messages/missed")
+            .route(actix_web::web::get().to(rest_message::missed_messages)),
+    )
+    .service(
+        actix_web::web::resource("/messages/{message_id}")
+            .route(actix_web::web::patch().to(rest_message::update_message))
+            .route(actix_web::web::delete().to(rest_message::revoke_message)),
+    )
+    .service(
+        actix_web::web::resource("/search")
+            .route(actix_web::web::get().to(rest_message::search)),
+    );
+    cfg.service(
+        actix_web::web::resource("/rooms")
+            .route(actix_web::web::get().to(rest_room::list_rooms))
+            .route(actix_web::web::post().to(rest_room::room_create)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}")
+            .route(actix_web::web::get().to(rest_room::room_get))
+            .route(actix_web::web::patch().to(rest_room::room_update))
+            .route(actix_web::web::delete().to(rest_room::room_delete)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/subscribe")
+            .route(actix_web::web::post().to(rest_room::subscribe))
+            .route(actix_web::web::delete().to(rest_room::unsubscribe)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/members")
+            .route(actix_web::web::post().to(rest_room::access_grant)),
+    )
+    .service(
+        actix_web::web::resource("/workspaces/{workspace_id}/members")
+            .route(actix_web::web::get().to(rest_member::list_workspace_members)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/members/{user_id}")
+            .route(actix_web::web::delete().to(rest_room::access_revoke)),
+    )
+    .service(
+        actix_web::web::resource("/workspaces/{workspace_id}/categories")
+            .route(actix_web::web::post().to(rest_room::category_create)),
+    )
+    .service(
+        actix_web::web::resource("/categories/{category_id}")
+            .route(actix_web::web::patch().to(rest_room::category_update))
+            .route(actix_web::web::delete().to(rest_room::category_delete)),
+    );
+    cfg.service(
+        actix_web::web::resource("/rooms/{room_id}/reactions")
+            .route(actix_web::web::post().to(rest_interact::reaction_add))
+            .route(actix_web::web::delete().to(rest_interact::reaction_remove)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/threads")
+            .route(actix_web::web::post().to(rest_interact::thread_create)),
+    )
+    .service(
+        actix_web::web::resource("/threads/{thread_id}/resolve")
+            .route(actix_web::web::patch().to(rest_interact::thread_resolve)),
+    )
+    .service(
+        actix_web::web::resource("/threads/{thread_id}/archive")
+            .route(actix_web::web::patch().to(rest_interact::thread_archive)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/pins")
+            .route(actix_web::web::post().to(rest_interact::pin_add))
+            .route(actix_web::web::delete().to(rest_interact::pin_remove)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/drafts")
+            .route(actix_web::web::put().to(rest_interact::draft_save))
+            .route(actix_web::web::delete().to(rest_interact::draft_clear)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/typing")
+            .route(actix_web::web::post().to(rest_interact::typing)),
+    );
+    cfg.service(
+        actix_web::web::resource("/rooms/{room_id}/read-receipt")
+            .route(actix_web::web::post().to(rest_member::read_receipt)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/dnd")
+            .route(actix_web::web::patch().to(rest_member::dnd_update)),
+    )
+    .service(
+        actix_web::web::resource("/notifications/{id}/read").route(
+            actix_web::web::patch().to(rest_member::notification_mark_read),
+        ),
+    )
+    .service(actix_web::web::resource("/notifications/read-all").route(
+        actix_web::web::post().to(rest_member::notification_mark_all_read),
+    ))
+    .service(
+        actix_web::web::resource("/notifications/{id}").route(
+            actix_web::web::delete().to(rest_member::notification_archive),
+        ),
+    )
+    .service(
+        actix_web::web::resource("/presence")
+            .route(actix_web::web::post().to(rest_member::presence_update)),
+    )
+    .service(
+        actix_web::web::resource("/custom-status").route(
+            actix_web::web::post().to(rest_member::custom_status_update),
+        ),
+    )
+    .service(
+        actix_web::web::resource("/invites")
+            .route(actix_web::web::post().to(rest_member::invite_create)),
+    )
+    .service(
+        actix_web::web::resource("/invites/accept")
+            .route(actix_web::web::post().to(rest_member::invite_accept)),
+    )
+    .service(
+        actix_web::web::resource("/invites/{id}")
+            .route(actix_web::web::delete().to(rest_member::invite_revoke)),
+    )
+    .service(
+        actix_web::web::resource("/workspaces/{workspace_id}/bans")
+            .route(actix_web::web::post().to(rest_member::ban_create)),
+    )
+    .service(
+        actix_web::web::resource("/workspaces/{workspace_id}/bans/{user_id}")
+            .route(actix_web::web::delete().to(rest_member::ban_remove)),
+    );
+    cfg.service(
+        actix_web::web::resource("/rooms/{room_id}/voice/join")
+            .route(actix_web::web::post().to(rest_voice::voice_join)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/voice/leave")
+            .route(actix_web::web::post().to(rest_voice::voice_leave)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/voice/mute")
+            .route(actix_web::web::post().to(rest_voice::voice_mute)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/voice/deaf")
+            .route(actix_web::web::post().to(rest_voice::voice_deaf)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/screen-share")
+            .route(actix_web::web::post().to(rest_voice::screen_share)),
+    );
+    cfg.service(
+        actix_web::web::resource("/rooms/{room_id}/ai/stop")
+            .route(actix_web::web::post().to(rest_ai::ai_stop)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/ai")
+            .route(actix_web::web::get().to(rest_ai::ai_list))
+            .route(actix_web::web::post().to(rest_ai::ai_add)),
+    )
+    .service(
+        actix_web::web::resource("/rooms/{room_id}/ai/{agent_session_id}")
+            .route(actix_web::web::delete().to(rest_ai::ai_remove)),
+    )
+    .service(
+        actix_web::web::resource("/users/summary/{username}")
+            .route(actix_web::web::get().to(rest_ai::user_summary)),
+    );
+    cfg.service(
+        actix_web::web::resource("/token")
+            .route(actix_web::web::post().to(token::generate_token)),
+    );
+    cfg.app_data(actix_web::web::Data::new(bus));
+}
diff --git a/lib/api/src/channel/rest.rs b/lib/api/src/channel/rest.rs
new file mode 100644
index 0000000..2f37e56
--- /dev/null
+++ b/lib/api/src/channel/rest.rs
@@ -0,0 +1,110 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::http::{WsHandler, WsInMessage, WsOutEvent};
+use channel::{ChannelBus, ChannelError};
+use session::SessionExt;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+pub(crate) fn extract_user(req: &HttpRequest) -> Result<Uuid, ApiError> {
+    req.get_session()
+        .user()
+        .ok_or_else(|| ApiError(service::error::AppError::Unauthorized))
+}
+
+pub(crate) fn channel_err(e: ChannelError) -> ApiError {
+    ApiError(match e {
+        ChannelError::Unauthorized | ChannelError::TokenInvalidOrExpired => {
+            service::error::AppError::Unauthorized
+        }
+        ChannelError::AccessDenied => {
+            service::error::AppError::PermissionDenied
+        }
+        ChannelError::Validation(msg) => {
+            service::error::AppError::BadRequest(msg)
+        }
+        ChannelError::RateLimitExceeded => {
+            service::error::AppError::BadRequest("rate limit exceeded".into())
+        }
+        ChannelError::RenewalLimitExceeded => {
+            service::error::AppError::BadRequest(
+                "renewal limit exceeded".into(),
+            )
+        }
+        ChannelError::RoomNotFound => {
+            service::error::AppError::NotFound("room not found".into())
+        }
+        ChannelError::UserNotFound => {
+            service::error::AppError::NotFound("user not found".into())
+        }
+        ChannelError::Internal(msg) => {
+            service::error::AppError::InternalServerError(msg)
+        }
+        ChannelError::Database(e) => {
+            service::error::AppError::InternalServerError(e.to_string())
+        }
+        ChannelError::Cache(e) => {
+            service::error::AppError::InternalServerError(e.to_string())
+        }
+        ChannelError::SocketIo(e) => {
+            service::error::AppError::InternalServerError(e.to_string())
+        }
+        ChannelError::Serialization(e) => {
+            service::error::AppError::InternalServerError(e.to_string())
+        }
+        ChannelError::Redis(e) => {
+            service::error::AppError::InternalServerError(e.to_string())
+        }
+        ChannelError::Storage(e) => {
+            service::error::AppError::InternalServerError(e.to_string())
+        }
+    })
+}
+
+pub(crate) fn ok_json(event: Option<WsOutEvent>) -> HttpResponse {
+    match event {
+        Some(e) => HttpResponse::Ok().json(e),
+        None => HttpResponse::NoContent().finish(),
+    }
+}
+
+pub(crate) fn created_json(event: Option<WsOutEvent>) -> HttpResponse {
+    match event {
+        Some(e) => HttpResponse::Created().json(e),
+        None => HttpResponse::NoContent().finish(),
+    }
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/ping",
+    responses((status = 200, description = "Pong with protocol version")),
+    tag = "channel",
+)]
+pub async fn ping(
+    req: HttpRequest,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let result = WsHandler::handle(&bus, user_id, WsInMessage::Ping)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/csrf",
+    responses((status = 200, description = "CSRF token")),
+    tag = "channel",
+)]
+pub async fn csrf_token(
+    req: HttpRequest,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let result = WsHandler::handle(&bus, user_id, WsInMessage::CsrfToken)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
diff --git a/lib/api/src/channel/rest_ai.rs b/lib/api/src/channel/rest_ai.rs
new file mode 100644
index 0000000..a29b5cf
--- /dev/null
+++ b/lib/api/src/channel/rest_ai.rs
@@ -0,0 +1,120 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::ChannelBus;
+use channel::http::{WsHandler, WsInMessage};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use super::rest::{channel_err, created_json, extract_user, ok_json};
+use crate::error::ApiError;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct AiAddRequest {
+    pub agent_session: Uuid,
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/rooms/{room_id}/ai",
+    responses((status = 200, description = "AI agents in room")),
+    tag = "channel",
+)]
+pub async fn ai_list(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::AiList {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/ai",
+    request_body = AiAddRequest,
+    responses((status = 201, description = "AI agent added to room")),
+    tag = "channel",
+)]
+pub async fn ai_add(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<AiAddRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::AiUpsert {
+        room: room_id.into_inner(),
+        model: body.agent_session,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(created_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}/ai/{agent_session_id}",
+    responses((status = 200, description = "AI agent removed from room")),
+    tag = "channel",
+)]
+pub async fn ai_remove(
+    req: HttpRequest,
+    path: web::Path<(Uuid, Uuid)>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let (room, agent_id) = path.into_inner();
+    let msg = WsInMessage::AiDelete { room, agent_id };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/ai/stop",
+    responses((status = 204, description = "AI agent stopped")),
+    tag = "channel",
+)]
+pub async fn ai_stop(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::AiStop {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/users/summary/{username}",
+    responses((status = 200, description = "User summary")),
+    tag = "channel",
+)]
+pub async fn user_summary(
+    req: HttpRequest,
+    username: web::Path<String>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::UserSummary {
+        username: username.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
diff --git a/lib/api/src/channel/rest_interact.rs b/lib/api/src/channel/rest_interact.rs
new file mode 100644
index 0000000..e160431
--- /dev/null
+++ b/lib/api/src/channel/rest_interact.rs
@@ -0,0 +1,274 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::ChannelBus;
+use channel::http::{WsHandler, WsInMessage};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use super::rest::{channel_err, created_json, extract_user, ok_json};
+use crate::error::ApiError;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct ReactionRequest {
+    pub message: Uuid,
+    pub emoji: String,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct ThreadCreateRequest {
+    pub parent: i64,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct TypingRequest {
+    pub action: TypingAction,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub enum TypingAction {
+    Start,
+    Stop,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/reactions",
+    request_body = ReactionRequest,
+    responses((status = 204, description = "Reaction added")),
+    tag = "channel",
+)]
+pub async fn reaction_add(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<ReactionRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ReactionAdd {
+        room: room_id.into_inner(),
+        message: body.message,
+        emoji: body.emoji.clone(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}/reactions",
+    request_body = ReactionRequest,
+    responses((status = 204, description = "Reaction removed")),
+    tag = "channel",
+)]
+pub async fn reaction_remove(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<ReactionRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ReactionRemove {
+        room: room_id.into_inner(),
+        message: body.message,
+        emoji: body.emoji.clone(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/threads",
+    request_body = ThreadCreateRequest,
+    responses((status = 201, description = "Thread created")),
+    tag = "channel",
+)]
+pub async fn thread_create(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<ThreadCreateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ThreadCreate {
+        room: room_id.into_inner(),
+        parent: body.parent,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(created_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/threads/{thread_id}/resolve",
+    responses((status = 200, description = "Thread resolved")),
+    tag = "channel",
+)]
+pub async fn thread_resolve(
+    req: HttpRequest,
+    thread_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ThreadResolve {
+        thread_id: thread_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/threads/{thread_id}/archive",
+    responses((status = 200, description = "Thread archived")),
+    tag = "channel",
+)]
+pub async fn thread_archive(
+    req: HttpRequest,
+    thread_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ThreadArchive {
+        thread_id: thread_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct PinRequest {
+    pub message: Uuid,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/pins",
+    request_body = PinRequest,
+    responses((status = 204, description = "Message pinned")),
+    tag = "channel",
+)]
+pub async fn pin_add(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<PinRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::PinAdd {
+        room: room_id.into_inner(),
+        message: body.message,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}/pins",
+    request_body = PinRequest,
+    responses((status = 204, description = "Pin removed")),
+    tag = "channel",
+)]
+pub async fn pin_remove(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<PinRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::PinRemove {
+        room: room_id.into_inner(),
+        message: body.message,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct DraftSaveRequest {
+    pub content: String,
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/ws/rooms/{room_id}/drafts",
+    request_body = DraftSaveRequest,
+    responses((status = 204, description = "Draft saved")),
+    tag = "channel",
+)]
+pub async fn draft_save(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<DraftSaveRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::DraftSave {
+        room: room_id.into_inner(),
+        content: body.content.clone(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}/drafts",
+    responses((status = 204, description = "Draft cleared")),
+    tag = "channel",
+)]
+pub async fn draft_clear(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::DraftClear {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/typing",
+    request_body = TypingRequest,
+    responses((status = 204, description = "Typing indicator broadcasted")),
+    tag = "channel",
+)]
+pub async fn typing(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<TypingRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let room = room_id.into_inner();
+    let msg = match body.action {
+        TypingAction::Start => WsInMessage::TypingStart { room },
+        TypingAction::Stop => WsInMessage::TypingStop { room },
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
diff --git a/lib/api/src/channel/rest_member.rs b/lib/api/src/channel/rest_member.rs
new file mode 100644
index 0000000..4a224f0
--- /dev/null
+++ b/lib/api/src/channel/rest_member.rs
@@ -0,0 +1,375 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::ChannelBus;
+use channel::http::{WsHandler, WsInMessage};
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use super::rest::{channel_err, created_json, extract_user, ok_json};
+use crate::error::ApiError;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct ReadReceiptRequest {
+    pub last_read_seq: i64,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct DndRequest {
+    pub do_not_disturb: Option<bool>,
+    pub dnd_start_hour: Option<i16>,
+    pub dnd_end_hour: Option<i16>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct NotificationMarkAllReadRequest {
+    pub workspace_id: Option<Uuid>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct PresenceUpdateRequest {
+    #[schema(example = "online")]
+    pub status: String,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct CustomStatusRequest {
+    pub emoji: Option<String>,
+    pub text: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct InviteCreateRequest {
+    pub workspace: Uuid,
+    pub room: Option<Uuid>,
+    pub max_uses: Option<i32>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct InviteAcceptRequest {
+    pub code: String,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct BanCreateRequest {
+    pub user: Uuid,
+    pub reason: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/read-receipt",
+    request_body = ReadReceiptRequest,
+    responses((status = 200, description = "Read receipt saved")),
+    tag = "channel",
+)]
+pub async fn read_receipt(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<ReadReceiptRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ReadReceipt {
+        room: room_id.into_inner(),
+        last_read_seq: body.last_read_seq,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/rooms/{room_id}/dnd",
+    request_body = DndRequest,
+    responses((status = 204, description = "DND updated")),
+    tag = "channel",
+)]
+pub async fn dnd_update(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<DndRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::StateUpdateDnd {
+        room: room_id.into_inner(),
+        do_not_disturb: body.do_not_disturb,
+        dnd_start_hour: body.dnd_start_hour,
+        dnd_end_hour: body.dnd_end_hour,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/notifications/{id}/read",
+    responses((status = 204, description = "Notification marked read")),
+    tag = "channel",
+)]
+pub async fn notification_mark_read(
+    req: HttpRequest,
+    id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::NotificationMarkRead {
+        id: id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/notifications/read-all",
+    request_body = NotificationMarkAllReadRequest,
+    responses((status = 204, description = "All notifications marked read")),
+    tag = "channel",
+)]
+pub async fn notification_mark_all_read(
+    req: HttpRequest,
+    body: web::Json<NotificationMarkAllReadRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::NotificationMarkAllRead {
+        workspace_id: body.workspace_id,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/notifications/{id}",
+    responses((status = 204, description = "Notification archived")),
+    tag = "channel",
+)]
+pub async fn notification_archive(
+    req: HttpRequest,
+    id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::NotificationArchive {
+        id: id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/presence",
+    request_body = PresenceUpdateRequest,
+    responses((status = 204, description = "Presence updated")),
+    tag = "channel",
+)]
+pub async fn presence_update(
+    req: HttpRequest,
+    body: web::Json<PresenceUpdateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let status: channel::event::presence::UserPresenceStatus =
+        serde_json::from_value(serde_json::Value::String(body.status.clone()))
+            .map_err(|e| {
+                ApiError(service::error::AppError::BadRequest(e.to_string()))
+            })?;
+    let msg = WsInMessage::PresenceUpdate { status };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/custom-status",
+    request_body = CustomStatusRequest,
+    responses((status = 204, description = "Custom status updated")),
+    tag = "channel",
+)]
+pub async fn custom_status_update(
+    req: HttpRequest,
+    body: web::Json<CustomStatusRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::CustomStatusUpdate {
+        emoji: body.emoji.clone(),
+        text: body.text.clone(),
+        expires_at: body.expires_at,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/invites",
+    request_body = InviteCreateRequest,
+    responses((status = 201, description = "Invite created")),
+    tag = "channel",
+)]
+pub async fn invite_create(
+    req: HttpRequest,
+    body: web::Json<InviteCreateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::InviteCreate {
+        workspace: body.workspace,
+        room: body.room,
+        max_uses: body.max_uses,
+        expires_at: body.expires_at,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(created_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/invites/accept",
+    request_body = InviteAcceptRequest,
+    responses((status = 200, description = "Invite accepted")),
+    tag = "channel",
+)]
+pub async fn invite_accept(
+    req: HttpRequest,
+    body: web::Json<InviteAcceptRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::InviteAccept {
+        code: body.code.clone(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/invites/{id}",
+    responses((status = 204, description = "Invite revoked")),
+    tag = "channel",
+)]
+pub async fn invite_revoke(
+    req: HttpRequest,
+    id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::InviteRevoke {
+        id: id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/workspaces/{workspace_id}/bans",
+    request_body = BanCreateRequest,
+    responses((status = 201, description = "User banned")),
+    tag = "channel",
+)]
+pub async fn ban_create(
+    req: HttpRequest,
+    workspace_id: web::Path<Uuid>,
+    body: web::Json<BanCreateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::BanCreate {
+        workspace: workspace_id.into_inner(),
+        user: body.user,
+        reason: body.reason.clone(),
+        expires_at: body.expires_at,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/workspaces/{workspace_id}/bans/{user_id}",
+    responses((status = 204, description = "User unbanned")),
+    tag = "channel",
+)]
+pub async fn ban_remove(
+    req: HttpRequest,
+    path: web::Path<(Uuid, Uuid)>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let (workspace, target_user) = path.into_inner();
+    let msg = WsInMessage::BanRemove {
+        workspace,
+        user: target_user,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct RoomMember {
+    pub id: Uuid,
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/workspaces/{workspace_id}/members",
+    responses((status = 200, description = "Workspace members list")),
+    tag = "channel",
+)]
+pub async fn list_workspace_members(
+    req: HttpRequest,
+    workspace_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let _user_id = extract_user(&req)?;
+    let workspace = workspace_id.into_inner();
+
+    let members = bus.list_workspace_members(workspace).await.map_err(channel_err)?;
+    let result: Vec<RoomMember> = members
+        .into_iter()
+        .map(|(id, username, display_name, avatar_url)| RoomMember {
+            id,
+            username,
+            display_name,
+            avatar_url,
+        })
+        .collect();
+
+    Ok(HttpResponse::Ok().json(result))
+}
diff --git a/lib/api/src/channel/rest_message.rs b/lib/api/src/channel/rest_message.rs
new file mode 100644
index 0000000..516ac60
--- /dev/null
+++ b/lib/api/src/channel/rest_message.rs
@@ -0,0 +1,225 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::ChannelBus;
+use channel::http::{WsHandler, WsInMessage};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use super::rest::{channel_err, created_json, extract_user, ok_json};
+use crate::error::ApiError;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct CreateMessageRequest {
+    pub content: String,
+    pub content_type: Option<String>,
+    pub thread: Option<Uuid>,
+    pub in_reply_to: Option<Uuid>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct UpdateMessageRequest {
+    pub content: String,
+}
+
+#[derive(Debug, Deserialize, utoipa::IntoParams)]
+pub struct MessageListParams {
+    pub before_seq: Option<i64>,
+    pub after_seq: Option<i64>,
+    pub limit: Option<u64>,
+}
+
+#[derive(Debug, Deserialize, utoipa::IntoParams)]
+pub struct MessageAroundParams {
+    pub seq: i64,
+    pub limit: Option<u64>,
+}
+
+#[derive(Debug, Deserialize, utoipa::IntoParams)]
+pub struct MissedMessagesParams {
+    pub after_seq: i64,
+    pub limit: Option<i64>,
+}
+
+#[derive(Debug, Deserialize, utoipa::IntoParams)]
+pub struct SearchParams {
+    pub q: String,
+    pub room: Option<Uuid>,
+    pub limit: Option<u64>,
+    pub offset: Option<u64>,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/messages",
+    request_body = CreateMessageRequest,
+    responses((status = 201, description = "Message created")),
+    tag = "channel",
+)]
+pub async fn create_message(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<CreateMessageRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::MessageCreate {
+        room: room_id.into_inner(),
+        content: body.content.clone(),
+        content_type: body.content_type.clone(),
+        thread: body.thread,
+        in_reply_to: body.in_reply_to,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(created_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/messages/{message_id}",
+    request_body = UpdateMessageRequest,
+    responses((status = 200, description = "Message updated")),
+    tag = "channel",
+)]
+pub async fn update_message(
+    req: HttpRequest,
+    message_id: web::Path<Uuid>,
+    body: web::Json<UpdateMessageRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::MessageUpdate {
+        message: message_id.into_inner(),
+        content: body.content.clone(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/messages/{message_id}",
+    responses((status = 200, description = "Message revoked")),
+    tag = "channel",
+)]
+pub async fn revoke_message(
+    req: HttpRequest,
+    message_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::MessageRevoke {
+        message: message_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/rooms/{room_id}/messages",
+    params(MessageListParams),
+    responses((status = 200, description = "Message list")),
+    tag = "channel",
+)]
+pub async fn list_messages(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    params: web::Query<MessageListParams>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::MessageList {
+        room: room_id.into_inner(),
+        before_seq: params.before_seq,
+        after_seq: params.after_seq,
+        limit: params.limit,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/rooms/{room_id}/messages/around",
+    params(MessageAroundParams),
+    responses((status = 200, description = "Messages around seq")),
+    tag = "channel",
+)]
+pub async fn messages_around(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    params: web::Query<MessageAroundParams>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::MessageAround {
+        room: room_id.into_inner(),
+        seq: params.seq,
+        limit: params.limit,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/rooms/{room_id}/messages/missed",
+    params(MissedMessagesParams),
+    responses((status = 200, description = "Missed messages")),
+    tag = "channel",
+)]
+pub async fn missed_messages(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    params: web::Query<MissedMessagesParams>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::MissedMessages {
+        room: room_id.into_inner(),
+        after_seq: params.after_seq,
+        limit: params.limit,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/search",
+    params(SearchParams),
+    responses((status = 200, description = "Search results")),
+    tag = "channel",
+)]
+pub async fn search(
+    req: HttpRequest,
+    params: web::Query<SearchParams>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::Search {
+        q: params.q.clone(),
+        room: params.room,
+        start_time: None,
+        end_time: None,
+        sender_id: None,
+        content_type: None,
+        limit: params.limit,
+        offset: params.offset,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
diff --git a/lib/api/src/channel/rest_room.rs b/lib/api/src/channel/rest_room.rs
new file mode 100644
index 0000000..2c969fd
--- /dev/null
+++ b/lib/api/src/channel/rest_room.rs
@@ -0,0 +1,321 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::ChannelBus;
+use channel::http::{WsHandler, WsInMessage};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use super::rest::{channel_err, created_json, extract_user, ok_json};
+use crate::error::ApiError;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct RoomCreateRequest {
+    pub workspace: Uuid,
+    pub room_name: String,
+    pub public: bool,
+    pub category: Option<Uuid>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct RoomUpdateRequest {
+    pub room_name: Option<String>,
+    pub public: Option<bool>,
+    pub category: Option<Uuid>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct AccessRequest {
+    pub user: Uuid,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct CategoryCreateRequest {
+    pub name: String,
+    pub position: Option<i32>,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct CategoryUpdateRequest {
+    pub name: Option<String>,
+    pub position: Option<i32>,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/rooms",
+    responses((status = 200, description = "List of rooms")),
+    tag = "channel",
+)]
+pub async fn list_rooms(
+    req: HttpRequest,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let rooms = bus.list_user_rooms(user_id)
+        .await
+        .map_err(channel_err)?;
+    let categories = bus.list_user_categories(user_id)
+        .await
+        .map_err(channel_err)?;
+    let workspace_id = if let Some(r) = rooms.first() {
+        Some(r.workspace_id)
+    } else {
+        bus.first_workspace_id(user_id).await.unwrap_or(None)
+    };
+    Ok(HttpResponse::Ok().json(serde_json::json!({
+        "rooms": rooms,
+        "categories": categories,
+        "workspace_id": workspace_id,
+    })))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/subscribe",
+    responses((status = 204, description = "Subscribed, user room cache refreshed")),
+    tag = "channel",
+)]
+pub async fn subscribe(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::Subscribe {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}/subscribe",
+    responses((status = 204, description = "Unsubscribed")),
+    tag = "channel",
+)]
+pub async fn unsubscribe(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::Unsubscribe {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/ws/rooms/{room_id}",
+    responses((status = 200, description = "Room info")),
+    tag = "channel",
+)]
+pub async fn room_get(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::RoomGet {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms",
+    request_body = RoomCreateRequest,
+    responses((status = 201, description = "Room created")),
+    tag = "channel",
+)]
+pub async fn room_create(
+    req: HttpRequest,
+    body: web::Json<RoomCreateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::RoomCreate {
+        workspace: body.workspace,
+        room_name: body.room_name.clone(),
+        public: body.public,
+        category: body.category,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(created_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/rooms/{room_id}",
+    request_body = RoomUpdateRequest,
+    responses((status = 200, description = "Room updated")),
+    tag = "channel",
+)]
+pub async fn room_update(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<RoomUpdateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::RoomUpdate {
+        room: room_id.into_inner(),
+        room_name: body.room_name.clone(),
+        public: body.public,
+        category: body.category,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}",
+    responses((status = 204, description = "Room deleted")),
+    tag = "channel",
+)]
+pub async fn room_delete(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::RoomDelete {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/members",
+    request_body = AccessRequest,
+    responses((status = 204, description = "Access granted")),
+    tag = "channel",
+)]
+pub async fn access_grant(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<AccessRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::AccessGrant {
+        room: room_id.into_inner(),
+        user: body.user,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/rooms/{room_id}/members/{user_id}",
+    responses((status = 204, description = "Access revoked")),
+    tag = "channel",
+)]
+pub async fn access_revoke(
+    req: HttpRequest,
+    path: web::Path<(Uuid, Uuid)>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let (room, target_user) = path.into_inner();
+    let msg = WsInMessage::AccessRevoke {
+        room,
+        user: target_user,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/workspaces/{workspace_id}/categories",
+    request_body = CategoryCreateRequest,
+    responses((status = 201, description = "Category created")),
+    tag = "channel",
+)]
+pub async fn category_create(
+    req: HttpRequest,
+    workspace_id: web::Path<Uuid>,
+    body: web::Json<CategoryCreateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::CategoryCreate {
+        workspace: workspace_id.into_inner(),
+        name: body.name.clone(),
+        position: body.position,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(created_json(result))
+}
+
+#[utoipa::path(
+    patch,
+    path = "/api/v1/ws/categories/{category_id}",
+    request_body = CategoryUpdateRequest,
+    responses((status = 200, description = "Category updated")),
+    tag = "channel",
+)]
+pub async fn category_update(
+    req: HttpRequest,
+    category_id: web::Path<Uuid>,
+    body: web::Json<CategoryUpdateRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::CategoryUpdate {
+        id: category_id.into_inner(),
+        name: body.name.clone(),
+        position: body.position,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/ws/categories/{category_id}",
+    responses((status = 204, description = "Category deleted")),
+    tag = "channel",
+)]
+pub async fn category_delete(
+    req: HttpRequest,
+    category_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::CategoryDelete {
+        id: category_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
diff --git a/lib/api/src/channel/rest_voice.rs b/lib/api/src/channel/rest_voice.rs
new file mode 100644
index 0000000..4b3c011
--- /dev/null
+++ b/lib/api/src/channel/rest_voice.rs
@@ -0,0 +1,137 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::ChannelBus;
+use channel::http::{WsHandler, WsInMessage};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use super::rest::{channel_err, extract_user, ok_json};
+use crate::error::ApiError;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct VoiceMuteRequest {
+    pub muted: bool,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct VoiceDeafRequest {
+    pub deafened: bool,
+}
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct ScreenShareRequest {
+    pub start: bool,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/voice/join",
+    responses((status = 204, description = "Joined voice channel")),
+    tag = "channel",
+)]
+pub async fn voice_join(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::VoiceJoin {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/voice/leave",
+    responses((status = 204, description = "Left voice channel")),
+    tag = "channel",
+)]
+pub async fn voice_leave(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::VoiceLeave {
+        room: room_id.into_inner(),
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/voice/mute",
+    request_body = VoiceMuteRequest,
+    responses((status = 204, description = "Mute toggled")),
+    tag = "channel",
+)]
+pub async fn voice_mute(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<VoiceMuteRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::VoiceMute {
+        room: room_id.into_inner(),
+        muted: body.muted,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/voice/deaf",
+    request_body = VoiceDeafRequest,
+    responses((status = 204, description = "Deaf toggled")),
+    tag = "channel",
+)]
+pub async fn voice_deaf(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<VoiceDeafRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::VoiceDeaf {
+        room: room_id.into_inner(),
+        deafened: body.deafened,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/rooms/{room_id}/screen-share",
+    request_body = ScreenShareRequest,
+    responses((status = 204, description = "Screen share toggled")),
+    tag = "channel",
+)]
+pub async fn screen_share(
+    req: HttpRequest,
+    room_id: web::Path<Uuid>,
+    body: web::Json<ScreenShareRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = extract_user(&req)?;
+    let msg = WsInMessage::ScreenShare {
+        room: room_id.into_inner(),
+        start: body.start,
+    };
+    let result = WsHandler::handle(&bus, user_id, msg)
+        .await
+        .map_err(channel_err)?;
+    Ok(ok_json(result))
+}
diff --git a/lib/api/src/channel/token.rs b/lib/api/src/channel/token.rs
new file mode 100644
index 0000000..fc12931
--- /dev/null
+++ b/lib/api/src/channel/token.rs
@@ -0,0 +1,53 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use channel::{ChannelBus, ChannelTokenApply, TOKEN_TTL_SECS};
+use serde::Deserialize;
+use session::SessionExt;
+
+use crate::error::ApiError;
+
+use super::rest::channel_err;
+
+#[derive(Debug, Deserialize, utoipa::ToSchema)]
+pub struct TokenRequest {
+    pub device_id: String,
+    pub client_id: String,
+}
+
+#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
+pub struct TokenResponse {
+    pub access_token: String,
+    pub expires_in_secs: u64,
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/ws/token",
+    request_body = TokenRequest,
+    responses((status = 200, body = TokenResponse)),
+    tag = "channel"
+)]
+pub async fn generate_token(
+    req: HttpRequest,
+    body: web::Json<TokenRequest>,
+    bus: web::Data<ChannelBus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = req
+        .get_session()
+        .user()
+        .ok_or_else(|| ApiError(service::error::AppError::Unauthorized))?;
+
+    let apply = ChannelTokenApply {
+        device_id: body.device_id.clone(),
+        client_id: body.client_id.clone(),
+    };
+
+    let token = bus
+        .apply_access_token(user_id, apply)
+        .await
+        .map_err(channel_err)?;
+
+    Ok(HttpResponse::Ok().json(TokenResponse {
+        access_token: token.access_token,
+        expires_in_secs: TOKEN_TTL_SECS,
+    }))
+}
diff --git a/lib/api/src/error.rs b/lib/api/src/error.rs
new file mode 100644
index 0000000..8c3cc40
--- /dev/null
+++ b/lib/api/src/error.rs
@@ -0,0 +1,91 @@
+use actix_web::{HttpResponse, error::ResponseError, http::StatusCode};
+use serde::Serialize;
+use service::error::AppError;
+
+pub fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+pub struct ApiError(pub AppError);
+
+impl From<AppError> for ApiError {
+    fn from(err: AppError) -> Self {
+        ApiError(err)
+    }
+}
+
+impl std::fmt::Display for ApiError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl std::fmt::Debug for ApiError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl ResponseError for ApiError {
+    fn status_code(&self) -> StatusCode {
+        match &self.0 {
+            AppError::Unauthorized => StatusCode::UNAUTHORIZED,
+            AppError::UserNotFound => StatusCode::NOT_FOUND,
+            AppError::InvalidPassword => StatusCode::UNAUTHORIZED,
+            AppError::PasswordTooWeak => StatusCode::BAD_REQUEST,
+            AppError::CaptchaError => StatusCode::BAD_REQUEST,
+            AppError::TwoFactorRequired => {
+                StatusCode::from_u16(402).unwrap_or(StatusCode::BAD_REQUEST)
+            }
+            AppError::TwoFactorAlreadyEnabled => StatusCode::CONFLICT,
+            AppError::TwoFactorNotSetup => StatusCode::NOT_FOUND,
+            AppError::InvalidTwoFactorCode => StatusCode::BAD_REQUEST,
+            AppError::TwoFactorNotEnabled => StatusCode::NOT_FOUND,
+            AppError::RsaGenerationError => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::RsaDecodeError => StatusCode::BAD_REQUEST,
+            AppError::UserNameExists => StatusCode::CONFLICT,
+            AppError::EmailExists => StatusCode::CONFLICT,
+            AppError::AccountAlreadyExists => StatusCode::CONFLICT,
+            AppError::TxnError => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::PasswordHashError(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::DatabaseError(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::DoMainNotSet => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::InternalError => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::InternalServerError(_) => {
+                StatusCode::INTERNAL_SERVER_ERROR
+            }
+            AppError::PermissionDenied => StatusCode::FORBIDDEN,
+            AppError::ProjectNotFound => StatusCode::NOT_FOUND,
+            AppError::NoPower => StatusCode::FORBIDDEN,
+            AppError::RoleParseError => StatusCode::BAD_REQUEST,
+            AppError::ProjectNameAlreadyExists => StatusCode::CONFLICT,
+            AppError::RepoNameAlreadyExists => StatusCode::CONFLICT,
+            AppError::AvatarUploadError(_) => StatusCode::BAD_REQUEST,
+            AppError::RepoNotFound => StatusCode::NOT_FOUND,
+            AppError::RepoForBidAccess => StatusCode::FORBIDDEN,
+            AppError::SerdeError(_) => StatusCode::BAD_REQUEST,
+            AppError::Io(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::BadRequest(_) => StatusCode::BAD_REQUEST,
+            AppError::Forbidden(_) => StatusCode::FORBIDDEN,
+            AppError::Conflict(_) => StatusCode::CONFLICT,
+            AppError::NotFound(_) => StatusCode::NOT_FOUND,
+            AppError::InvalidResetToken => StatusCode::BAD_REQUEST,
+            AppError::ResetTokenExpired => StatusCode::BAD_REQUEST,
+            AppError::ResetTokenUsed => StatusCode::BAD_REQUEST,
+            AppError::IssueNotFound => StatusCode::NOT_FOUND,
+            AppError::LabelNotFound => StatusCode::NOT_FOUND,
+            AppError::MilestoneNotFound => StatusCode::NOT_FOUND,
+            AppError::PullRequestNotFound => StatusCode::NOT_FOUND,
+            AppError::CommentNotFound => StatusCode::NOT_FOUND,
+            AppError::GitRpcError(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            AppError::AiError(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        }
+    }
+
+    fn error_response(&self) -> HttpResponse {
+        let status = self.status_code();
+        let message = self.0.to_string();
+        HttpResponse::build(status)
+            .json(serde_json::json!({ "error": message }))
+    }
+}
diff --git a/lib/api/src/git/archive.rs b/lib/api/src/git/archive.rs
new file mode 100644
index 0000000..dd4427f
--- /dev/null
+++ b/lib/api/src/git/archive.rs
@@ -0,0 +1,47 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ArchiveQuery {
+    #[serde(default = "default_format")]
+    pub format: String,
+    pub tree: Option<String>,
+    pub prefix: Option<String>,
+    pub pathspec: Option<Vec<String>>,
+}
+
+fn default_format() -> String {
+    "tar".to_string()
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/archive",
+    params(WkRepoPath, ArchiveQuery),
+    responses((status = 200, description = "Archive download")),
+    security(("session" = []))
+)]
+pub async fn archive(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<ArchiveQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    match query.format.as_str() {
+        "zip" => ok_json(service.git_archive_zip(&session, &wk, &repo, None).await?),
+        _ => ok_json(service.git_archive_tar(&session, &wk, &repo, None).await?),
+    }
+}
diff --git a/lib/api/src/git/blame.rs b/lib/api/src/git/blame.rs
new file mode 100644
index 0000000..46d6bb1
--- /dev/null
+++ b/lib/api/src/git/blame.rs
@@ -0,0 +1,62 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct BlameQuery {
+    pub path: String,
+    pub rev: Option<String>,
+    pub start_line: Option<u32>,
+    pub end_line: Option<u32>,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/blame",
+    params(WkRepoPath, BlameQuery),
+    responses((status = 200, description = "Blame result", body = dto::BlameFileResponseDto)),
+    security(("session" = []))
+)]
+pub async fn blame_file(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<BlameQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+
+    match (query.start_line, query.end_line) {
+        (Some(start), Some(end)) => {
+            let data: dto::BlameFileResponseDto = service
+                .git_blame_hunk(
+                    &session, &wk, &repo, query.path.clone(),
+                    query.rev.clone(), start, end,
+                )
+                .await?
+                .into();
+            ok_json(data)
+        }
+        _ => {
+            let data: dto::BlameFileResponseDto = service
+                .git_blame_file(
+                    &session, &wk, &repo, query.path.clone(),
+                    query.rev.clone(), None,
+                )
+                .await?
+                .into();
+            ok_json(data)
+        }
+    }
+}
diff --git a/lib/api/src/git/blob.rs b/lib/api/src/git/blob.rs
new file mode 100644
index 0000000..95ab810
--- /dev/null
+++ b/lib/api/src/git/blob.rs
@@ -0,0 +1,97 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoBlobPath {
+    pub wk: String,
+    pub repo: String,
+    pub oid: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct BlobPathQuery {
+    pub path: Option<String>,
+}
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct BlobInfoResponse {
+    #[serde(flatten)]
+    pub load: dto::BlobLoadResponseDto,
+    pub size: u64,
+    pub is_binary: bool,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/blobs/{oid}",
+    params(WkRepoBlobPath, BlobPathQuery),
+    responses((status = 200, description = "Blob info", body = BlobInfoResponse)),
+    security(("session" = []))
+)]
+pub async fn blob_info(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoBlobPath>,
+    query: web::Query<BlobPathQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoBlobPath { wk, repo, oid } = path.into_inner();
+    let path_opt = query.path.clone().unwrap_or_default();
+
+    let load: dto::BlobLoadResponseDto = service
+        .git_blob_load(&session, &wk, &repo, oid.clone(), path_opt.clone())
+        .await?
+        .into();
+    let size_resp: dto::BlobSizeResponseDto = service
+        .git_blob_size(&session, &wk, &repo, oid.clone(), path_opt)
+        .await?
+        .into();
+    let binary_resp: dto::BlobIsBinaryResponseDto = service
+        .git_blob_is_binary(&session, &wk, &repo, oid)
+        .await?
+        .into();
+
+    ok_json(BlobInfoResponse {
+        load,
+        size: size_resp.size,
+        is_binary: binary_resp.is_binary,
+    })
+}
+
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct BlobUploadBody {
+    pub path: String,
+    pub blob: Vec<u8>,
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/blobs",
+    params(WkRepoPath),
+    request_body = BlobUploadBody,
+    responses((status = 200, description = "Upload result", body = dto::BlobUploadResponseDto)),
+    security(("session" = []))
+)]
+pub async fn blob_upload(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<BlobUploadBody>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let p = params.into_inner();
+    let data: dto::BlobUploadResponseDto = service
+        .git_blob_upload(&session, &wk, &repo, p.path, p.blob)
+        .await?
+        .into();
+    ok_json(data)
+}
diff --git a/lib/api/src/git/branch.rs b/lib/api/src/git/branch.rs
new file mode 100644
index 0000000..4d8063d
--- /dev/null
+++ b/lib/api/src/git/branch.rs
@@ -0,0 +1,205 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{AppService, Pagination};
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoBranchPath {
+    pub wk: String,
+    pub repo: String,
+    pub name: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct BranchDeleteQuery {
+    #[serde(default)]
+    pub force: bool,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct BranchListQuery {
+    #[serde(default)]
+    pub summary: bool,
+    #[serde(default)]
+    pub default_only: bool,
+}
+
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct RenameBranchBody {
+    pub new_branch: String,
+    #[serde(default)]
+    pub force: bool,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches",
+    params(WkRepoPath, Pagination, BranchListQuery),
+    responses((status = 200, description = "Branch list or summary", body = dto::BranchListResponseDto)),
+    security(("session" = []))
+)]
+pub async fn list_branches(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    pagination: web::Query<Pagination>,
+    query: web::Query<BranchListQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    if query.summary {
+        let data: dto::BranchSummaryResponseDto = service
+            .git_branch_summary(&session, &wk, &repo)
+            .await?
+            .into();
+        return ok_json(data);
+    }
+    if query.default_only {
+        let data: dto::BranchHeadResponseDto = service
+            .git_branch_head(&session, &wk, &repo)
+            .await?
+            .into();
+        return ok_json(data);
+    }
+    let data: dto::BranchListResponseDto = service
+        .git_branch_list(&session, &wk, &repo, pagination.into_inner())
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches/{name}",
+    params(WkRepoBranchPath),
+    responses((status = 200, description = "Branch info", body = dto::BranchInfoResponseDto)),
+    security(("session" = []))
+)]
+pub async fn branch_info(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoBranchPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoBranchPath { wk, repo, name } = path.into_inner();
+    let data: dto::BranchInfoResponseDto = service
+        .git_branch_info(&session, &wk, &repo, name)
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches",
+    params(WkRepoPath),
+    request_body = Object, description = "BranchForkParams { name, oid, force }",
+    responses((status = 200, description = "Branch created")),
+    security(("session" = []))
+)]
+pub async fn fork_branch(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<git::rpc::proto::BranchForkParams>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .git_branch_fork(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    patch, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches/{name}",
+    params(WkRepoBranchPath),
+    request_body = RenameBranchBody,
+    responses((status = 200, description = "Branch renamed")),
+    security(("session" = []))
+)]
+pub async fn rename_branch(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoBranchPath>,
+    body: web::Json<RenameBranchBody>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoBranchPath { wk, repo, name } = path.into_inner();
+    let body = body.into_inner();
+    let params = git::rpc::proto::BranchReNameParams {
+        old_branch: name,
+        new_branch: body.new_branch,
+        force: body.force,
+    };
+    let data = service
+        .git_branch_rename(&session, &wk, &repo, params)
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches/{name}",
+    params(WkRepoBranchPath, BranchDeleteQuery),
+    responses((status = 200, description = "Branch deleted")),
+    security(("session" = []))
+)]
+pub async fn delete_branch(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoBranchPath>,
+    query: web::Query<BranchDeleteQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoBranchPath { wk, repo, name } = path.into_inner();
+    let params = git::rpc::proto::BranchDeleteParams {
+        name,
+        force: query.force,
+    };
+    let data = service
+        .git_branch_delete(&session, &wk, &repo, params)
+        .await?;
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct AheadBehindQuery {
+    pub remote_branch: String,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches/{name}/ahead-behind",
+    params(WkRepoBranchPath, AheadBehindQuery),
+    responses((status = 200, description = "Ahead/behind counts", body = dto::BranchAheadBehindResponseDto)),
+    security(("session" = []))
+)]
+pub async fn ahead_behind(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoBranchPath>,
+    query: web::Query<AheadBehindQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoBranchPath { wk, repo, name } = path.into_inner();
+    let data: dto::BranchAheadBehindResponseDto = service
+        .git_branch_ahead_behind(&session, &wk, &repo, name, query.remote_branch.clone())
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/branches/{name}/upstream",
+    params(WkRepoBranchPath),
+    responses((status = 200, description = "Upstream branch", body = dto::BranchUpstreamResponseDto)),
+    security(("session" = []))
+)]
+pub async fn branch_upstream(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoBranchPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoBranchPath { wk, repo, name } = path.into_inner();
+    let data: dto::BranchUpstreamResponseDto = service
+        .git_branch_upstream(&session, &wk, &repo, name)
+        .await?
+        .into();
+    ok_json(data)
+}
diff --git a/lib/api/src/git/commit.rs b/lib/api/src/git/commit.rs
new file mode 100644
index 0000000..099fbaa
--- /dev/null
+++ b/lib/api/src/git/commit.rs
@@ -0,0 +1,169 @@
+use actix_web::{HttpResponse, web};
+use git::rpc::proto as p;
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoCommitPath {
+    pub wk: String,
+    pub repo: String,
+    pub oid: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct HistoryQuery {
+    pub limit: Option<u64>,
+    pub skip: Option<u64>,
+    pub sort: Option<i32>,
+    pub branch: Option<String>,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct CommitListQuery {
+    #[serde(default)]
+    pub summary: bool,
+    #[serde(default)]
+    pub refs: bool,
+    pub prefix: Option<String>,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/commits",
+    params(WkRepoPath, CommitListQuery),
+    responses(
+        (status = 200, description = "Commit list / summary / refs / prefix", body = dto::CommitHistoryResponseDto),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_commits(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<CommitListQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+
+    if let Some(prefix) = &query.prefix {
+        let data: dto::CommitPrefixResponseDto = service
+            .git_commit_prefix(&session, &wk, &repo, prefix.clone())
+            .await?
+            .into();
+        return ok_json(data);
+    }
+    if query.refs {
+        let data: dto::CommitRefsResponseDto = service
+            .git_commit_refs(&session, &wk, &repo)
+            .await?
+            .into();
+        return ok_json(data);
+    }
+    if query.summary {
+        let data: dto::CommitSummaryResponseDto = service
+            .git_commit_summary(&session, &wk, &repo)
+            .await?
+            .into();
+        return ok_json(data);
+    }
+    let data: dto::CommitHistoryResponseDto = service
+        .git_commit_history(&session, &wk, &repo, 20, 0, 0, None)
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/commits/history",
+    params(WkRepoPath, HistoryQuery),
+    responses((status = 200, description = "Commit history", body = dto::CommitHistoryResponseDto)),
+    security(("session" = []))
+)]
+pub async fn commit_history(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<HistoryQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data: dto::CommitHistoryResponseDto = service
+        .git_commit_history(
+            &session, &wk, &repo,
+            query.limit.unwrap_or(20),
+            query.skip.unwrap_or(0),
+            query.sort.unwrap_or(0),
+            query.branch.clone(),
+        )
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/commits/{oid}",
+    params(WkRepoCommitPath),
+    responses((status = 200, description = "Commit info", body = dto::CommitInfoResponseDto)),
+    security(("session" = []))
+)]
+pub async fn commit_info(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoCommitPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoCommitPath { wk, repo, oid } = path.into_inner();
+    let data: dto::CommitInfoResponseDto = service
+        .git_commit_info(&session, &wk, &repo, oid)
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/commits/walk",
+    params(WkRepoPath),
+    request_body = Object, description = "CommitWalkParams",
+    responses((status = 200, description = "Walk result", body = dto::CommitHistoryResponseDto)),
+    security(("session" = []))
+)]
+pub async fn commit_walk(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<p::CommitWalkParams>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let proto_resp = service
+        .git_commit_walk(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(dto::CommitHistoryResponseDto {
+        commits: proto_resp.commits.into_iter().map(Into::into).collect(),
+    })
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/commits/cherry-pick",
+    params(WkRepoPath),
+    request_body = Object, description = "CommitCherryPickParams",
+    responses((status = 200, description = "Cherry-pick result", body = dto::CherryPickResponseDto)),
+    security(("session" = []))
+)]
+pub async fn cherry_pick(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<p::CommitCherryPickParams>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data: dto::CherryPickResponseDto = service
+        .git_cherry_pick(&session, &wk, &repo, params.into_inner())
+        .await?
+        .into();
+    ok_json(data)
+}
diff --git a/lib/api/src/git/commit_status.rs b/lib/api/src/git/commit_status.rs
new file mode 100644
index 0000000..cdf3c55
--- /dev/null
+++ b/lib/api/src/git/commit_status.rs
@@ -0,0 +1,81 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use service::git::commit_status::{
+    CombinedCommitStatus, CommitStatusResponse, CreateCommitStatus,
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok_created<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Created().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct CommitShaPath {
+    pub wk: String,
+    pub repo: String,
+    pub sha: String,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/commits/{sha}/statuses",
+    params(CommitShaPath),
+    responses((status = 200, body = Vec<CommitStatusResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_statuses(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommitShaPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(service.git_commit_status_list_by_name(
+        &session, &path.wk, &path.repo, &path.sha,
+    ).await?)
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/commits/{sha}/status",
+    params(CommitShaPath),
+    responses((status = 200, body = CombinedCommitStatus)),
+    security(("session" = []))
+)]
+pub async fn combined_status(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommitShaPath>,
+) -> Result<HttpResponse, ApiError> {
+    ok_json(service.git_commit_status_combined_by_name(
+        &session, &path.wk, &path.repo, &path.sha,
+    ).await?)
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/statuses/{sha}",
+    params(CommitShaPath),
+    request_body = CreateCommitStatus,
+    responses((status = 201, body = CommitStatusResponse)),
+    security(("session" = []))
+)]
+pub async fn create_status(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommitShaPath>,
+    body: web::Json<CreateCommitStatus>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_created(service.git_commit_status_create_by_name(
+        &session, user_id, &path.wk, &path.repo, &path.sha, body.into_inner(),
+    ).await?)
+}
diff --git a/lib/api/src/git/compare.rs b/lib/api/src/git/compare.rs
new file mode 100644
index 0000000..9a3af8c
--- /dev/null
+++ b/lib/api/src/git/compare.rs
@@ -0,0 +1,43 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use service::git::compare::CompareResponse;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/compare/{basehead}",
+    params(
+        ("wk" = String, Path),
+        ("repo" = String, Path),
+        ("basehead" = String, Path, description = "Comparison in format 'base...head'"),
+    ),
+    responses((status = 200, body = CompareResponse)),
+    security(("session" = []))
+)]
+pub async fn compare(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, String, String)>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, basehead) = path.into_inner();
+
+    let (base, head) = basehead
+        .split_once("...")
+        .ok_or_else(|| ApiError(service::error::AppError::BadRequest(
+            "basehead must be in format 'base...head'".to_string(),
+        )))?;
+
+    ok_json(service.git_compare(&session, &wk, &repo_name, base, head).await?)
+}
diff --git a/lib/api/src/git/contents.rs b/lib/api/src/git/contents.rs
new file mode 100644
index 0000000..abb0145
--- /dev/null
+++ b/lib/api/src/git/contents.rs
@@ -0,0 +1,105 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use service::git::contents::{ContentResponse, CreateContent, UpdateContent};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ContentQuery {
+    pub r#ref: Option<String>,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/contents/{path}",
+    params(WkRepoPath, ("path" = String, Path), ContentQuery),
+    responses((status = 200, body = ContentResponse)),
+    security(("session" = []))
+)]
+pub async fn get_contents(
+    session: Session,
+    service: web::Data<AppService>,
+    info: web::Path<(String, String, String)>,
+    query: web::Query<ContentQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, file_path) = info.into_inner();
+    ok_json(service.git_contents_get_by_name(
+        &session, &wk, &repo_name, &file_path, query.r#ref.as_deref(),
+    ).await?)
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/contents/{path}",
+    params(WkRepoPath, ("path" = String, Path)),
+    request_body = CreateContent,
+    responses((status = 201, body = ContentResponse)),
+    security(("session" = []))
+)]
+pub async fn create_contents(
+    session: Session,
+    service: web::Data<AppService>,
+    info: web::Path<(String, String, String)>,
+    body: web::Json<CreateContent>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, file_path) = info.into_inner();
+    let resp = service.git_contents_create_by_name(
+        &session, &wk, &repo_name, &file_path, body.into_inner(),
+    ).await?;
+    Ok(HttpResponse::Created().json(resp))
+}
+
+#[utoipa::path(
+    put, path = "/api/v1/workspace/{wk}/repos/{repo}/contents/{path}",
+    params(WkRepoPath, ("path" = String, Path)),
+    request_body = UpdateContent,
+    responses((status = 200, body = ContentResponse)),
+    security(("session" = []))
+)]
+pub async fn update_contents(
+    session: Session,
+    service: web::Data<AppService>,
+    info: web::Path<(String, String, String)>,
+    body: web::Json<UpdateContent>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, file_path) = info.into_inner();
+    ok_json(service.git_contents_update_by_name(
+        &session, &wk, &repo_name, &file_path, body.into_inner(),
+    ).await?)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct DeleteContentQuery {
+    pub message: String,
+    pub sha: String,
+    pub branch: Option<String>,
+}
+
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/contents/{path}",
+    params(WkRepoPath, ("path" = String, Path), DeleteContentQuery),
+    responses((status = 204)),
+    security(("session" = []))
+)]
+pub async fn delete_contents(
+    session: Session,
+    service: web::Data<AppService>,
+    info: web::Path<(String, String, String)>,
+    query: web::Query<DeleteContentQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, file_path) = info.into_inner();
+    service.git_contents_delete_by_name(
+        &session, &wk, &repo_name, &file_path, &query.message, &query.sha, query.branch.as_deref(),
+    ).await?;
+    Ok(HttpResponse::NoContent().finish())
+}
diff --git a/lib/api/src/git/contributor.rs b/lib/api/src/git/contributor.rs
new file mode 100644
index 0000000..6e75901
--- /dev/null
+++ b/lib/api/src/git/contributor.rs
@@ -0,0 +1,34 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{AppService, Pagination};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/contributors",
+    params(WkRepoPath, Pagination),
+    responses((status = 200, description = "Contributor list", body = Vec<service::git::contributor::ContributorDto>)),
+    security(("session" = []))
+)]
+pub async fn list_contributors(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .git_repo_contributors(&session, &wk, &repo, pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/diff.rs b/lib/api/src/git/diff.rs
new file mode 100644
index 0000000..0a8d60f
--- /dev/null
+++ b/lib/api/src/git/diff.rs
@@ -0,0 +1,87 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct DiffQuery {
+    pub old_oid: Option<String>,
+    pub new_oid: Option<String>,
+    pub old_tree: Option<String>,
+    pub new_tree: Option<String>,
+    pub tree_oid: Option<String>,
+    #[serde(default = "default_mode")]
+    pub mode: String,
+    pub path: Option<String>,
+}
+
+fn default_mode() -> String {
+    "patch".to_string()
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/diff",
+    params(WkRepoPath, DiffQuery),
+    responses((status = 200, description = "Diff result")),
+    security(("session" = []))
+)]
+pub async fn diff(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<DiffQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    if let (Some(old_tree), Some(new_tree)) = (&query.old_tree, &query.new_tree) {
+        let proto_resp = service
+            .git_diff_tree_to_tree(&session, &wk, &repo, old_tree.clone(), new_tree.clone(), None)
+            .await?;
+        let data: dto::DiffResultDto = proto_resp.result.unwrap_or_default().into();
+        return ok_json(data);
+    }
+    if let Some(tree_oid) = &query.tree_oid {
+        let proto_resp = service
+            .git_diff_index_to_tree(&session, &wk, &repo, tree_oid.clone(), None)
+            .await?;
+        let data: dto::DiffResultDto = proto_resp.result.unwrap_or_default().into();
+        return ok_json(data);
+    }
+    let old_oid = query.old_oid.clone().unwrap_or_default();
+    let new_oid = query.new_oid.clone().unwrap_or_default();
+
+    match query.mode.as_str() {
+        "stats" => {
+            let proto_resp = service
+                .git_diff_stats(&session, &wk, &repo, old_oid, new_oid, None)
+                .await?;
+            let data: dto::DiffStatsDto = proto_resp.result.and_then(|r| r.stats).unwrap_or_default().into();
+            ok_json(data)
+        }
+        "side-by-side" => {
+            let proto_resp = service
+                .git_diff_patch_side_by_side(&session, &wk, &repo, old_oid, new_oid, None)
+                .await?;
+            let data: dto::SideBySideDiffResultDto = proto_resp.result.unwrap_or_default().into();
+            ok_json(data)
+        }
+        _ => {
+            let proto_resp = service
+                .git_diff_patch(&session, &wk, &repo, old_oid, new_oid, None)
+                .await?;
+            let data: dto::DiffResultDto = proto_resp.result.unwrap_or_default().into();
+            ok_json(data)
+        }
+    }
+}
diff --git a/lib/api/src/git/dto.rs b/lib/api/src/git/dto.rs
new file mode 100644
index 0000000..f12aa73
--- /dev/null
+++ b/lib/api/src/git/dto.rs
@@ -0,0 +1,888 @@
+use base64::Engine;
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+use git::rpc::proto as p;
+
+fn oid_val(oid: Option<p::ObjectId>) -> String {
+    oid.map(|o| o.value).unwrap_or_default()
+}
+
+fn oid_opt(oid: Option<p::ObjectId>) -> Option<String> {
+    oid.map(|o| o.value)
+}
+
+fn oid_vec(oids: Vec<p::ObjectId>) -> Vec<String> {
+    oids.into_iter().map(|o| o.value).collect()
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct ObjectIdDto {
+    pub value: String,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchListItemDto {
+    pub name: String,
+    pub oid: String,
+    pub is_head: bool,
+    pub is_remote: bool,
+    pub is_current: bool,
+    pub upstream: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchListResponseDto {
+    pub branches: Vec<BranchListItemDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchInfoResponseDto {
+    pub branch: Option<BranchListItemDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchSummaryDto {
+    pub local_count: u64,
+    pub remote_count: u64,
+    pub all_count: u64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchSummaryResponseDto {
+    pub summary: Option<BranchSummaryDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchHeadResponseDto {
+    pub head_name: String,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchAheadBehindResponseDto {
+    pub ahead: u64,
+    pub behind: u64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BranchUpstreamResponseDto {
+    pub upstream_name: String,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitSignatureDto {
+    pub name: String,
+    pub email: String,
+    pub time_secs: i64,
+    pub offset_minutes: i32,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitMetaDto {
+    pub oid: String,
+    pub message: String,
+    pub summary: String,
+    pub author: Option<CommitSignatureDto>,
+    pub committer: Option<CommitSignatureDto>,
+    pub tree_id: Option<String>,
+    pub parent_ids: Vec<String>,
+    pub encoding: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitInfoResponseDto {
+    pub commit: Option<CommitMetaDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitHistoryResponseDto {
+    pub commits: Vec<CommitMetaDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitSummaryDto {
+    pub head: Option<CommitMetaDto>,
+    pub count: u64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitSummaryResponseDto {
+    pub summary: Option<CommitSummaryDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitRefInfoDto {
+    pub name: String,
+    pub target: String,
+    pub is_remote: bool,
+    pub is_tag: bool,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitRefsResponseDto {
+    pub refs: Vec<CommitRefInfoDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitPrefixResponseDto {
+    pub oid: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitExistsResponseDto {
+    pub exists: bool,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CherryPickResponseDto {
+    pub oid: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum TreeKindDto {
+    Blob,
+    Tree,
+    LfsPointer,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TreeEntryDto {
+    pub name: String,
+    pub oid: String,
+    pub kind: TreeKindDto,
+    pub filemode: u32,
+    pub is_binary: bool,
+    pub is_lfs: bool,
+    pub last_commit_message: Option<String>,
+    pub last_commit_time: Option<String>,
+    pub last_commit_author_name: Option<String>,
+    pub last_commit_author_email: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TreeEntriesResponseDto {
+    pub entries: Vec<TreeEntryDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TreeEntryByPathResponseDto {
+    pub entry: Option<TreeEntryDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TreeInfoDto {
+    pub oid: String,
+    pub entry_count: u64,
+    pub is_empty: bool,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct ResolveTreeResponseDto {
+    pub info: Option<TreeInfoDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlobLoadResponseDto {
+    pub blob: String,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlobSizeResponseDto {
+    pub size: u64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlobExistsResponseDto {
+    pub exists: bool,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlobIsBinaryResponseDto {
+    pub is_binary: bool,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlobUploadResponseDto {
+    pub id: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagItemDto {
+    pub name: String,
+    pub oid: String,
+    pub target: String,
+    pub is_annotated: bool,
+    pub message: Option<String>,
+    pub tagger: Option<String>,
+    pub tagger_email: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagListResponseDto {
+    pub tags: Vec<TagItemDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagInfoResponseDto {
+    pub tag: Option<TagItemDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagSummaryDto {
+    pub total_count: u64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagSummaryResponseDto {
+    pub summary: Option<TagSummaryDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagInitResponseDto {
+    pub oid: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct TagUpdateMessageResponseDto {
+    pub oid: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitBlameHunkDto {
+    pub commit_oid: Option<String>,
+    pub final_start_line: u32,
+    pub final_lines: u32,
+    pub orig_start_line: u32,
+    pub orig_lines: u32,
+    pub boundary: bool,
+    pub orig_path: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct CommitBlameLineDto {
+    pub commit_oid: Option<String>,
+    pub line_no: u32,
+    pub content: String,
+    pub orig_path: Option<String>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlameFileResponseDto {
+    pub hunks: Vec<CommitBlameHunkDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct BlameLinesResponseDto {
+    pub lines: Vec<CommitBlameLineDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum DiffDeltaStatusDto {
+    Unmodified,
+    Added,
+    Deleted,
+    Modified,
+    Renamed,
+    Copied,
+    Typechange,
+    Conflicted,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DiffFileDto {
+    pub oid: Option<String>,
+    pub path: Option<String>,
+    pub size: u64,
+    pub is_binary: bool,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DiffHunkDto {
+    pub old_start: u32,
+    pub old_lines: u32,
+    pub new_start: u32,
+    pub new_lines: u32,
+    pub header: String,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DiffLineDto {
+    pub content: String,
+    pub origin: String,
+    pub old_lineno: Option<u32>,
+    pub new_lineno: Option<u32>,
+    pub num_lines: u32,
+    pub content_offset: i64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DiffDeltaDto {
+    pub status: i32,
+    pub old_file: Option<DiffFileDto>,
+    pub new_file: Option<DiffFileDto>,
+    pub nfiles: u32,
+    pub hunks: Vec<DiffHunkDto>,
+    pub lines: Vec<DiffLineDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DiffStatsDto {
+    pub files_changed: u64,
+    pub insertions: u64,
+    pub deletions: u64,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct DiffResultDto {
+    pub stats: Option<DiffStatsDto>,
+    pub deltas: Vec<DiffDeltaDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum SideBySideChangeTypeDto {
+    Unchanged,
+    Added,
+    Removed,
+    Modified,
+    Empty,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct SideBySideLineDto {
+    pub left_line_no: Option<u32>,
+    pub right_line_no: Option<u32>,
+    pub left_content: String,
+    pub right_content: String,
+    pub change_type: i32,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct SideBySideFileDto {
+    pub path: String,
+    pub additions: u64,
+    pub deletions: u64,
+    pub is_binary: bool,
+    pub is_rename: bool,
+    pub lines: Vec<SideBySideLineDto>,
+}
+
+#[derive(Serialize, Deserialize, ToSchema)]
+pub struct SideBySideDiffResultDto {
+    pub files: Vec<SideBySideFileDto>,
+    pub total_additions: u64,
+    pub total_deletions: u64,
+}
+
+impl From<p::ObjectId> for ObjectIdDto {
+    fn from(o: p::ObjectId) -> Self {
+        ObjectIdDto { value: o.value }
+    }
+}
+
+impl From<p::BranchListItem> for BranchListItemDto {
+    fn from(b: p::BranchListItem) -> Self {
+        BranchListItemDto {
+            name: b.name,
+            oid: oid_val(b.oid),
+            is_head: b.is_head,
+            is_remote: b.is_remote,
+            is_current: b.is_current,
+            upstream: b.upstream,
+        }
+    }
+}
+
+impl From<p::BranchListResponse> for BranchListResponseDto {
+    fn from(r: p::BranchListResponse) -> Self {
+        BranchListResponseDto {
+            branches: r.branches.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::BranchInfoResponse> for BranchInfoResponseDto {
+    fn from(r: p::BranchInfoResponse) -> Self {
+        BranchInfoResponseDto {
+            branch: r.branch.map(Into::into),
+        }
+    }
+}
+
+impl From<p::BranchSummary> for BranchSummaryDto {
+    fn from(s: p::BranchSummary) -> Self {
+        BranchSummaryDto {
+            local_count: s.local_count,
+            remote_count: s.remote_count,
+            all_count: s.all_count,
+        }
+    }
+}
+
+impl From<p::BranchSummaryResponse> for BranchSummaryResponseDto {
+    fn from(r: p::BranchSummaryResponse) -> Self {
+        BranchSummaryResponseDto {
+            summary: r.summary.map(Into::into),
+        }
+    }
+}
+
+impl From<p::BranchHeadResponse> for BranchHeadResponseDto {
+    fn from(r: p::BranchHeadResponse) -> Self {
+        BranchHeadResponseDto { head_name: r.head_name }
+    }
+}
+
+impl From<p::BranchAheadBehindResponse> for BranchAheadBehindResponseDto {
+    fn from(r: p::BranchAheadBehindResponse) -> Self {
+        BranchAheadBehindResponseDto {
+            ahead: r.ahead,
+            behind: r.behind,
+        }
+    }
+}
+
+impl From<p::BranchUpstreamResponse> for BranchUpstreamResponseDto {
+    fn from(r: p::BranchUpstreamResponse) -> Self {
+        BranchUpstreamResponseDto {
+            upstream_name: r.upstream_name,
+        }
+    }
+}
+
+impl From<p::CommitSignature> for CommitSignatureDto {
+    fn from(s: p::CommitSignature) -> Self {
+        CommitSignatureDto {
+            name: s.name,
+            email: s.email,
+            time_secs: s.time_secs,
+            offset_minutes: s.offset_minutes,
+        }
+    }
+}
+
+impl From<p::CommitMeta> for CommitMetaDto {
+    fn from(c: p::CommitMeta) -> Self {
+        CommitMetaDto {
+            oid: oid_val(c.oid),
+            message: c.message,
+            summary: c.summary,
+            author: c.author.map(Into::into),
+            committer: c.committer.map(Into::into),
+            tree_id: oid_opt(c.tree_id),
+            parent_ids: oid_vec(c.parent_ids),
+            encoding: c.encoding,
+        }
+    }
+}
+
+impl From<p::CommitInfoResponse> for CommitInfoResponseDto {
+    fn from(r: p::CommitInfoResponse) -> Self {
+        CommitInfoResponseDto {
+            commit: r.commit.map(Into::into),
+        }
+    }
+}
+
+impl From<p::CommitHistoryResponse> for CommitHistoryResponseDto {
+    fn from(r: p::CommitHistoryResponse) -> Self {
+        CommitHistoryResponseDto {
+            commits: r.commits.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::CommitSummary> for CommitSummaryDto {
+    fn from(s: p::CommitSummary) -> Self {
+        CommitSummaryDto {
+            head: s.head.map(Into::into),
+            count: s.count,
+        }
+    }
+}
+
+impl From<p::CommitSummaryResponse> for CommitSummaryResponseDto {
+    fn from(r: p::CommitSummaryResponse) -> Self {
+        CommitSummaryResponseDto {
+            summary: r.summary.map(Into::into),
+        }
+    }
+}
+
+impl From<p::CommitRefInfo> for CommitRefInfoDto {
+    fn from(r: p::CommitRefInfo) -> Self {
+        CommitRefInfoDto {
+            name: r.name,
+            target: oid_val(r.target),
+            is_remote: r.is_remote,
+            is_tag: r.is_tag,
+        }
+    }
+}
+
+impl From<p::CommitRefsResponse> for CommitRefsResponseDto {
+    fn from(r: p::CommitRefsResponse) -> Self {
+        CommitRefsResponseDto {
+            refs: r.refs.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::CommitPrefixResponse> for CommitPrefixResponseDto {
+    fn from(r: p::CommitPrefixResponse) -> Self {
+        CommitPrefixResponseDto { oid: oid_opt(r.oid) }
+    }
+}
+
+impl From<p::CommitExistsResponse> for CommitExistsResponseDto {
+    fn from(r: p::CommitExistsResponse) -> Self {
+        CommitExistsResponseDto { exists: r.exists }
+    }
+}
+
+impl From<p::CherryPickResponse> for CherryPickResponseDto {
+    fn from(r: p::CherryPickResponse) -> Self {
+        CherryPickResponseDto { oid: oid_opt(r.oid) }
+    }
+}
+
+impl From<p::CherryPickSequenceResponse> for CherryPickResponseDto {
+    fn from(r: p::CherryPickSequenceResponse) -> Self {
+        CherryPickResponseDto { oid: oid_opt(r.oid) }
+    }
+}
+
+fn tree_kind_from_proto(kind: i32) -> TreeKindDto {
+    match kind {
+        0 => TreeKindDto::Blob,
+        1 => TreeKindDto::Tree,
+        2 => TreeKindDto::LfsPointer,
+        _ => TreeKindDto::Blob,
+    }
+}
+
+impl From<p::TreeEntry> for TreeEntryDto {
+    fn from(e: p::TreeEntry) -> Self {
+        fn opt(s: String) -> Option<String> {
+            if s.is_empty() { None } else { Some(s) }
+        }
+        TreeEntryDto {
+            name: e.name,
+            oid: oid_val(e.oid),
+            kind: tree_kind_from_proto(e.kind),
+            filemode: e.filemode,
+            is_binary: e.is_binary,
+            is_lfs: e.is_lfs,
+            last_commit_message: opt(e.last_commit_message),
+            last_commit_time: opt(e.last_commit_time),
+            last_commit_author_name: opt(e.last_commit_author_name),
+            last_commit_author_email: opt(e.last_commit_author_email),
+        }
+    }
+}
+
+impl From<p::TreeEntriesResponse> for TreeEntriesResponseDto {
+    fn from(r: p::TreeEntriesResponse) -> Self {
+        TreeEntriesResponseDto {
+            entries: r.entries.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::TreeEntryByPathResponse> for TreeEntryByPathResponseDto {
+    fn from(r: p::TreeEntryByPathResponse) -> Self {
+        TreeEntryByPathResponseDto {
+            entry: r.entry.map(Into::into),
+        }
+    }
+}
+
+impl From<p::TreeEntryByPathFromCommitResponse> for TreeEntryByPathResponseDto {
+    fn from(r: p::TreeEntryByPathFromCommitResponse) -> Self {
+        TreeEntryByPathResponseDto {
+            entry: r.entry.map(Into::into),
+        }
+    }
+}
+
+impl From<p::TreeInfo> for TreeInfoDto {
+    fn from(i: p::TreeInfo) -> Self {
+        TreeInfoDto {
+            oid: oid_val(i.oid),
+            entry_count: i.entry_count,
+            is_empty: i.is_empty,
+        }
+    }
+}
+
+impl From<p::ResolveTreeResponse> for ResolveTreeResponseDto {
+    fn from(r: p::ResolveTreeResponse) -> Self {
+        ResolveTreeResponseDto {
+            info: r.info.map(Into::into),
+        }
+    }
+}
+
+impl From<p::BlobLoadResponse> for BlobLoadResponseDto {
+    fn from(r: p::BlobLoadResponse) -> Self {
+        BlobLoadResponseDto {
+            blob: base64::engine::general_purpose::STANDARD.encode(&r.blob),
+        }
+    }
+}
+
+impl From<p::BlobSizeResponse> for BlobSizeResponseDto {
+    fn from(r: p::BlobSizeResponse) -> Self {
+        BlobSizeResponseDto { size: r.size }
+    }
+}
+
+impl From<p::BlobExistsResponse> for BlobExistsResponseDto {
+    fn from(r: p::BlobExistsResponse) -> Self {
+        BlobExistsResponseDto { exists: r.exists }
+    }
+}
+
+impl From<p::BlobIsBinaryResponse> for BlobIsBinaryResponseDto {
+    fn from(r: p::BlobIsBinaryResponse) -> Self {
+        BlobIsBinaryResponseDto { is_binary: r.is_binary }
+    }
+}
+
+impl From<p::BlobUploadResponse> for BlobUploadResponseDto {
+    fn from(r: p::BlobUploadResponse) -> Self {
+        BlobUploadResponseDto { id: oid_opt(r.id) }
+    }
+}
+
+impl From<p::TagItem> for TagItemDto {
+    fn from(t: p::TagItem) -> Self {
+        TagItemDto {
+            name: t.name,
+            oid: oid_val(t.oid),
+            target: oid_val(t.target),
+            is_annotated: t.is_annotated,
+            message: t.message,
+            tagger: t.tagger,
+            tagger_email: t.tagger_email,
+        }
+    }
+}
+
+impl From<p::TagListResponse> for TagListResponseDto {
+    fn from(r: p::TagListResponse) -> Self {
+        TagListResponseDto {
+            tags: r.tags.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::TagInfoResponse> for TagInfoResponseDto {
+    fn from(r: p::TagInfoResponse) -> Self {
+        TagInfoResponseDto { tag: r.tag.map(Into::into) }
+    }
+}
+
+impl From<p::TagSummary> for TagSummaryDto {
+    fn from(s: p::TagSummary) -> Self {
+        TagSummaryDto { total_count: s.total_count }
+    }
+}
+
+impl From<p::TagSummaryResponse> for TagSummaryResponseDto {
+    fn from(r: p::TagSummaryResponse) -> Self {
+        TagSummaryResponseDto { summary: r.summary.map(Into::into) }
+    }
+}
+
+impl From<p::TagInitResponse> for TagInitResponseDto {
+    fn from(r: p::TagInitResponse) -> Self {
+        TagInitResponseDto { oid: oid_opt(r.oid) }
+    }
+}
+
+impl From<p::TagUpdateMessageResponse> for TagUpdateMessageResponseDto {
+    fn from(r: p::TagUpdateMessageResponse) -> Self {
+        TagUpdateMessageResponseDto { oid: oid_opt(r.oid) }
+    }
+}
+
+impl From<p::CommitBlameHunk> for CommitBlameHunkDto {
+    fn from(h: p::CommitBlameHunk) -> Self {
+        CommitBlameHunkDto {
+            commit_oid: oid_opt(h.commit_oid),
+            final_start_line: h.final_start_line,
+            final_lines: h.final_lines,
+            orig_start_line: h.orig_start_line,
+            orig_lines: h.orig_lines,
+            boundary: h.boundary,
+            orig_path: h.orig_path,
+        }
+    }
+}
+
+impl From<p::CommitBlameLine> for CommitBlameLineDto {
+    fn from(l: p::CommitBlameLine) -> Self {
+        CommitBlameLineDto {
+            commit_oid: oid_opt(l.commit_oid),
+            line_no: l.line_no,
+            content: l.content,
+            orig_path: l.orig_path,
+        }
+    }
+}
+
+impl From<p::BlameFileResponse> for BlameFileResponseDto {
+    fn from(r: p::BlameFileResponse) -> Self {
+        BlameFileResponseDto {
+            hunks: r.hunks.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::BlameHunkResponse> for BlameFileResponseDto {
+    fn from(r: p::BlameHunkResponse) -> Self {
+        BlameFileResponseDto {
+            hunks: r.hunks.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::BlameLinesResponse> for BlameLinesResponseDto {
+    fn from(r: p::BlameLinesResponse) -> Self {
+        BlameLinesResponseDto {
+            lines: r.lines.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::DiffDeltaStatus> for DiffDeltaStatusDto {
+    fn from(s: p::DiffDeltaStatus) -> Self {
+        match s {
+            p::DiffDeltaStatus::Unmodified => DiffDeltaStatusDto::Unmodified,
+            p::DiffDeltaStatus::Added => DiffDeltaStatusDto::Added,
+            p::DiffDeltaStatus::Deleted => DiffDeltaStatusDto::Deleted,
+            p::DiffDeltaStatus::Modified => DiffDeltaStatusDto::Modified,
+            p::DiffDeltaStatus::Renamed => DiffDeltaStatusDto::Renamed,
+            p::DiffDeltaStatus::Copied => DiffDeltaStatusDto::Copied,
+            p::DiffDeltaStatus::Typechange => DiffDeltaStatusDto::Typechange,
+            p::DiffDeltaStatus::Conflicted => DiffDeltaStatusDto::Conflicted,
+        }
+    }
+}
+
+impl From<p::DiffFile> for DiffFileDto {
+    fn from(f: p::DiffFile) -> Self {
+        DiffFileDto {
+            oid: oid_opt(f.oid),
+            path: f.path,
+            size: f.size,
+            is_binary: f.is_binary,
+        }
+    }
+}
+
+impl From<p::DiffHunk> for DiffHunkDto {
+    fn from(h: p::DiffHunk) -> Self {
+        DiffHunkDto {
+            old_start: h.old_start,
+            old_lines: h.old_lines,
+            new_start: h.new_start,
+            new_lines: h.new_lines,
+            header: h.header,
+        }
+    }
+}
+
+impl From<p::DiffLine> for DiffLineDto {
+    fn from(l: p::DiffLine) -> Self {
+        DiffLineDto {
+            content: l.content,
+            origin: l.origin,
+            old_lineno: l.old_lineno,
+            new_lineno: l.new_lineno,
+            num_lines: l.num_lines,
+            content_offset: l.content_offset,
+        }
+    }
+}
+
+impl From<p::DiffDelta> for DiffDeltaDto {
+    fn from(d: p::DiffDelta) -> Self {
+        DiffDeltaDto {
+            status: d.status,
+            old_file: d.old_file.map(Into::into),
+            new_file: d.new_file.map(Into::into),
+            nfiles: d.nfiles,
+            hunks: d.hunks.into_iter().map(Into::into).collect(),
+            lines: d.lines.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::DiffStats> for DiffStatsDto {
+    fn from(s: p::DiffStats) -> Self {
+        DiffStatsDto {
+            files_changed: s.files_changed,
+            insertions: s.insertions,
+            deletions: s.deletions,
+        }
+    }
+}
+
+impl From<p::DiffResult> for DiffResultDto {
+    fn from(r: p::DiffResult) -> Self {
+        DiffResultDto {
+            stats: r.stats.map(Into::into),
+            deltas: r.deltas.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::SideBySideChangeType> for SideBySideChangeTypeDto {
+    fn from(t: p::SideBySideChangeType) -> Self {
+        match t {
+            p::SideBySideChangeType::Unchanged => SideBySideChangeTypeDto::Unchanged,
+            p::SideBySideChangeType::Added => SideBySideChangeTypeDto::Added,
+            p::SideBySideChangeType::Removed => SideBySideChangeTypeDto::Removed,
+            p::SideBySideChangeType::Modified => SideBySideChangeTypeDto::Modified,
+            p::SideBySideChangeType::Empty => SideBySideChangeTypeDto::Empty,
+        }
+    }
+}
+
+impl From<p::SideBySideLine> for SideBySideLineDto {
+    fn from(l: p::SideBySideLine) -> Self {
+        SideBySideLineDto {
+            left_line_no: l.left_line_no,
+            right_line_no: l.right_line_no,
+            left_content: l.left_content,
+            right_content: l.right_content,
+            change_type: l.change_type,
+        }
+    }
+}
+
+impl From<p::SideBySideFile> for SideBySideFileDto {
+    fn from(f: p::SideBySideFile) -> Self {
+        SideBySideFileDto {
+            path: f.path,
+            additions: f.additions,
+            deletions: f.deletions,
+            is_binary: f.is_binary,
+            is_rename: f.is_rename,
+            lines: f.lines.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::SideBySideDiffResult> for SideBySideDiffResultDto {
+    fn from(r: p::SideBySideDiffResult) -> Self {
+        SideBySideDiffResultDto {
+            files: r.files.into_iter().map(Into::into).collect(),
+            total_additions: r.total_additions,
+            total_deletions: r.total_deletions,
+        }
+    }
+}
diff --git a/lib/api/src/git/fork.rs b/lib/api/src/git/fork.rs
new file mode 100644
index 0000000..79e39c8
--- /dev/null
+++ b/lib/api/src/git/fork.rs
@@ -0,0 +1,62 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService, Pagination,
+    git::fork::{CreateFork, ForkResponse},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+use super::repo::WkRepoPath;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/forks",
+    params(WkRepoPath),
+    request_body = CreateFork,
+    responses(
+        (status = 200, body = ForkResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Cannot fork private repo"),
+        (status = 409, description = "Fork already exists"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_fork(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<CreateFork>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_fork_create(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/forks",
+    params(WkRepoPath, Pagination),
+    responses(
+        (status = 200, body = Vec<ForkResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_forks(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_fork_list(&session, &wk, &repo, pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/init.rs b/lib/api/src/git/init.rs
new file mode 100644
index 0000000..eb13bfe
--- /dev/null
+++ b/lib/api/src/git/init.rs
@@ -0,0 +1,56 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{AppService, git::init::{CloneRepo, CreateRepo}};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkPath {
+    pub wk: String,
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos",
+    params(("wk" = String, Path, description = "Workspace name")),
+    request_body = CreateRepo,
+    responses((status = 200, description = "Repo created"), (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"), (status = 409, description = "Repo name exists")),
+    security(("session" = []))
+)]
+pub async fn create_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkPath>,
+    params: web::Json<CreateRepo>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner().wk;
+    let data = service
+        .git_init_bare(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/clone",
+    params(("wk" = String, Path, description = "Workspace name")),
+    request_body = CloneRepo,
+    responses((status = 200, description = "Repo cloned"), (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"), (status = 409, description = "Repo name exists")),
+    security(("session" = []))
+)]
+pub async fn clone_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkPath>,
+    params: web::Json<CloneRepo>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner().wk;
+    let data = service
+        .git_clone_bare(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/language.rs b/lib/api/src/git/language.rs
new file mode 100644
index 0000000..36a98b2
--- /dev/null
+++ b/lib/api/src/git/language.rs
@@ -0,0 +1,31 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/languages",
+    params(WkRepoPath),
+    responses((status = 200, description = "Language stats", body = Vec<service::git::language::LanguageStatDto>)),
+    security(("session" = []))
+)]
+pub async fn get_languages(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_languages(&session, &wk, &repo).await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/mod.rs b/lib/api/src/git/mod.rs
new file mode 100644
index 0000000..c6703ff
--- /dev/null
+++ b/lib/api/src/git/mod.rs
@@ -0,0 +1,241 @@
+pub mod archive;
+pub mod blame;
+pub mod blob;
+pub mod branch;
+pub mod commit;
+pub mod commit_status;
+pub mod compare;
+pub mod contents;
+pub mod contributor;
+pub mod diff;
+pub mod dto;
+pub mod fork;
+pub mod init;
+pub mod language;
+pub mod protect;
+pub mod readme;
+pub mod refs;
+pub mod release;
+pub mod repo;
+pub mod star;
+pub mod tag;
+pub mod tree;
+pub mod watch;
+pub mod webhook;
+
+use actix_web::{web, web::ServiceConfig};
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("")
+            .route(web::post().to(init::create_repo))
+            .route(web::get().to(repo::list_repos)),
+    );
+    cfg.service(
+        web::resource("/clone")
+            .route(web::post().to(init::clone_repo)),
+    );
+    cfg.service(
+        web::resource("/{repo}")
+            .route(web::get().to(repo::get_repo))
+            .route(web::put().to(repo::update_repo))
+            .route(web::delete().to(repo::delete_repo)),
+    );
+    cfg.service(
+        web::resource("/{repo}/archive")
+            .route(web::post().to(repo::archive_repo)),
+    );
+    cfg.service(
+        web::resource("/{repo}/transfer")
+            .route(web::post().to(repo::transfer_repo)),
+    );
+    cfg.service(
+        web::resource("/{repo}/topics")
+            .route(web::get().to(repo::get_topics))
+            .route(web::put().to(repo::update_topics)),
+    );
+    cfg.service(
+        web::resource("/{repo}/forks")
+            .route(web::get().to(fork::list_forks))
+            .route(web::post().to(fork::create_fork)),
+    );
+    cfg.service(
+        web::resource("/{repo}/protect")
+            .route(web::get().to(protect::list_protects))
+            .route(web::post().to(protect::create_protect)),
+    );
+    cfg.service(
+        web::resource("/{repo}/protect/{protect_id}")
+            .route(web::put().to(protect::update_protect))
+            .route(web::delete().to(protect::delete_protect)),
+    );
+    cfg.service(
+        web::resource("/{repo}/webhooks")
+            .route(web::get().to(webhook::list_webhooks))
+            .route(web::post().to(webhook::create_webhook)),
+    );
+    cfg.service(
+        web::resource("/{repo}/webhooks/{webhook_id}")
+            .route(web::put().to(webhook::update_webhook))
+            .route(web::delete().to(webhook::delete_webhook)),
+    );
+    cfg.service(
+        web::resource("/{repo}/webhooks/{webhook_id}/deliveries")
+            .route(web::get().to(webhook::list_deliveries)),
+    );
+    cfg.service(
+        web::scope("/{repo}/git")
+            .service(
+                web::resource("/branches")
+                    .route(web::get().to(branch::list_branches))
+                    .route(web::post().to(branch::fork_branch)),
+            )
+            .service(
+                web::resource("/branches/{name}")
+                    .route(web::get().to(branch::branch_info))
+                    .route(web::patch().to(branch::rename_branch))
+                    .route(web::delete().to(branch::delete_branch)),
+            )
+            .service(
+                web::resource("/branches/{name}/ahead-behind")
+                    .route(web::get().to(branch::ahead_behind)),
+            )
+            .service(
+                web::resource("/branches/{name}/upstream")
+                    .route(web::get().to(branch::branch_upstream)),
+            )
+            .service(
+                web::resource("/commits")
+                    .route(web::get().to(commit::list_commits)),
+            )
+            .service(
+                web::resource("/commits/history")
+                    .route(web::get().to(commit::commit_history)),
+            )
+            .service(
+                web::resource("/commits/{oid}")
+                    .route(web::get().to(commit::commit_info)),
+            )
+            .service(
+                web::resource("/commits/walk")
+                    .route(web::post().to(commit::commit_walk)),
+            )
+            .service(
+                web::resource("/commits/cherry-pick")
+                    .route(web::post().to(commit::cherry_pick)),
+            )
+            .service(
+                web::resource("/blobs")
+                    .route(web::post().to(blob::blob_upload)),
+            )
+            .service(
+                web::resource("/blobs/{oid}")
+                    .route(web::get().to(blob::blob_info)),
+            )
+            .service(
+                web::resource("/blame")
+                    .route(web::get().to(blame::blame_file)),
+            )
+            .service(
+                web::resource("/trees/{oid}")
+                    .route(web::get().to(tree::tree_entries)),
+            )
+            .service(
+                web::resource("/trees/{tree_oid}/entries")
+                    .route(web::get().to(tree::tree_entry_by_path)),
+            )
+            .service(
+                web::resource("/commits/{oid}/tree")
+                    .route(web::get().to(tree::tree_entry_by_path_from_commit)),
+            )
+            .service(
+                web::resource("/diff")
+                    .route(web::get().to(diff::diff)),
+            )
+            .service(
+                web::resource("/diff/branches")
+                    .route(web::get().to(readme::diff_branches)),
+            )
+            .service(
+                web::resource("/tags")
+                    .route(web::get().to(tag::list_tags))
+                    .route(web::post().to(tag::init_tag)),
+            )
+            .service(
+                web::resource("/tags/{name}")
+                    .route(web::get().to(tag::tag_info))
+                    .route(web::patch().to(tag::update_tag))
+                    .route(web::delete().to(tag::delete_tag)),
+            )
+            .service(
+                web::resource("/archive")
+                    .route(web::get().to(archive::archive)),
+            )
+            .service(
+                web::resource("/star")
+                    .route(web::get().to(star::star_status))
+                    .route(web::post().to(star::star_repo))
+                    .route(web::delete().to(star::unstar_repo)),
+            )
+            .service(
+                web::resource("/watch")
+                    .route(web::get().to(watch::watch_status))
+                    .route(web::post().to(watch::watch_repo))
+                    .route(web::delete().to(watch::unwatch_repo)),
+            )
+            .service(
+                web::resource("/contributors")
+                    .route(web::get().to(contributor::list_contributors)),
+            )
+            .service(
+                web::resource("/languages")
+                    .route(web::get().to(language::get_languages)),
+            )
+            .service(
+                web::resource("/readme")
+                    .route(web::get().to(readme::get_readme)),
+            )
+            .service(
+                web::resource("/refs")
+                    .route(web::get().to(refs::list_refs)),
+            ),
+    );
+    cfg.service(
+        web::resource("/{repo}/releases")
+            .route(web::get().to(release::list_releases))
+            .route(web::post().to(release::create_release)),
+    )
+    .service(
+        web::resource("/{repo}/releases/{id}")
+            .route(web::get().to(release::get_release))
+            .route(web::patch().to(release::update_release))
+            .route(web::delete().to(release::delete_release)),
+    )
+    .service(
+        web::resource("/{repo}/releases/tags/{tag}")
+            .route(web::get().to(release::get_release_by_tag))
+            .route(web::delete().to(release::delete_release_by_tag)),
+    )
+    .service(
+        web::resource("/{repo}/statuses/{sha}")
+            .route(web::post().to(commit_status::create_status)),
+    )
+    .service(
+        web::resource("/{repo}/commits/{sha}/status")
+            .route(web::get().to(commit_status::combined_status)),
+    )
+    .service(
+        web::resource("/{repo}/commits/{sha}/statuses")
+            .route(web::get().to(commit_status::list_statuses)),
+    )
+    .service(
+        web::resource("/{repo}/compare/{basehead}")
+            .route(web::get().to(compare::compare)),
+    )
+    .service(
+        web::resource("/{repo}/contents/{path:.*}")
+            .route(web::get().to(contents::get_contents))
+            .route(web::post().to(contents::create_contents))
+            .route(web::put().to(contents::update_contents))
+            .route(web::delete().to(contents::delete_contents)),
+    );
+}
diff --git a/lib/api/src/git/protect.rs b/lib/api/src/git/protect.rs
new file mode 100644
index 0000000..81e60a1
--- /dev/null
+++ b/lib/api/src/git/protect.rs
@@ -0,0 +1,134 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, Pagination,
+    git::protect::{CreateProtect, ProtectResponse, UpdateProtect},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+use super::repo::WkRepoPath;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ProtectPath {
+    pub wk: String,
+    pub repo: String,
+    pub protect_id: uuid::Uuid,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/protect",
+    params(WkRepoPath, Pagination),
+    responses(
+        (status = 200, body = Vec<ProtectResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_protects(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_protect_list(&session, &wk, &repo, pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/protect",
+    params(WkRepoPath),
+    request_body = CreateProtect,
+    responses(
+        (status = 200, body = ProtectResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_protect(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<CreateProtect>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_protect_create(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/protect/{protect_id}",
+    params(ProtectPath),
+    request_body = UpdateProtect,
+    responses(
+        (status = 200, body = ProtectResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Rule not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_protect(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ProtectPath>,
+    params: web::Json<UpdateProtect>,
+) -> Result<HttpResponse, ApiError> {
+    let ProtectPath {
+        wk,
+        repo,
+        protect_id,
+    } = path.into_inner();
+    let data = service
+        .repo_protect_update(
+            &session,
+            &wk,
+            &repo,
+            protect_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/protect/{protect_id}",
+    params(ProtectPath),
+    responses(
+        (status = 200, description = "Rule deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Rule not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn delete_protect(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ProtectPath>,
+) -> Result<HttpResponse, ApiError> {
+    let ProtectPath {
+        wk,
+        repo,
+        protect_id,
+    } = path.into_inner();
+    service
+        .repo_protect_delete(&session, &wk, &repo, protect_id)
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/git/readme.rs b/lib/api/src/git/readme.rs
new file mode 100644
index 0000000..36e98c5
--- /dev/null
+++ b/lib/api/src/git/readme.rs
@@ -0,0 +1,87 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/readme",
+    params(WkRepoPath),
+    responses((status = 200, description = "README content", body = Option<service::git::readme::ReadmeDto>)),
+    security(("session" = []))
+)]
+pub async fn get_readme(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_readme(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/diff/branches",
+    params(("wk" = String, Path), ("repo" = String, Path), ("old_branch" = String, Query), ("new_branch" = String, Query)),
+    responses((status = 200, description = "Branch diff", body = dto::DiffResultDto)),
+    security(("session" = []))
+)]
+pub async fn diff_branches(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<BranchDiffQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let q = query.into_inner();
+
+    let old_info = service
+        .git_branch_info(&session, &wk, &repo, q.old_branch.clone())
+        .await?;
+    let new_info = service
+        .git_branch_info(&session, &wk, &repo, q.new_branch.clone())
+        .await?;
+
+    let old_oid = old_info
+        .branch
+        .and_then(|b| b.oid)
+        .map(|o| o.value)
+        .unwrap_or_default();
+    let new_oid = new_info
+        .branch
+        .and_then(|b| b.oid)
+        .map(|o| o.value)
+        .unwrap_or_default();
+
+    if old_oid.is_empty() || new_oid.is_empty() {
+        return Err(service::error::AppError::NotFound(
+            "could not resolve one or both branches".to_string(),
+        )
+        .into());
+    }
+
+    let proto_resp = service
+        .git_diff_patch(&session, &wk, &repo, old_oid, new_oid, None)
+        .await?;
+
+    let data: dto::DiffResultDto = proto_resp.result.unwrap_or_default().into();
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct BranchDiffQuery {
+    pub old_branch: String,
+    pub new_branch: String,
+}
diff --git a/lib/api/src/git/refs.rs b/lib/api/src/git/refs.rs
new file mode 100644
index 0000000..96f95d8
--- /dev/null
+++ b/lib/api/src/git/refs.rs
@@ -0,0 +1,41 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use service::git::refs::GitRefResponse;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct RefQuery {
+    pub r#ref: Option<String>,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/refs",
+    params(WkRepoPath, RefQuery),
+    responses((status = 200, body = Vec<GitRefResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_refs(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    query: web::Query<RefQuery>,
+) -> Result<HttpResponse, ApiError> {
+    if let Some(ref_name) = &query.r#ref {
+        let r = service.git_ref_get_by_name(&session, &path.wk, &path.repo, ref_name).await?;
+        return ok_json(vec![r]);
+    }
+    ok_json(service.git_ref_list_by_name(&session, &path.wk, &path.repo).await?)
+}
diff --git a/lib/api/src/git/release.rs b/lib/api/src/git/release.rs
new file mode 100644
index 0000000..060788a
--- /dev/null
+++ b/lib/api/src/git/release.rs
@@ -0,0 +1,146 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use service::git::release::{CreateRelease, ReleaseResponse, UpdateRelease};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok_created<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Created().json(data))
+}
+
+fn ok_empty() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::NoContent().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ReleaseIdPath {
+    pub wk: String,
+    pub repo: String,
+    pub id: Uuid,
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/releases",
+    params(WkRepoPath),
+    responses((status = 200, body = Vec<ReleaseResponse>)),
+    security(("session" = []))
+)]
+pub async fn list_releases(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.git_release_list_by_name(&session, user_id, &path.wk, &path.repo).await?)
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/releases/{id}",
+    params(ReleaseIdPath),
+    responses((status = 200, body = ReleaseResponse)),
+    security(("session" = []))
+)]
+pub async fn get_release(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ReleaseIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.git_release_get_by_name(&session, user_id, &path.wk, &path.repo, path.id).await?)
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/releases/tags/{tag}",
+    params(WkRepoPath, ("tag" = String, Path)),
+    responses((status = 200, body = ReleaseResponse)),
+    security(("session" = []))
+)]
+pub async fn get_release_by_tag(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, String, String)>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, tag) = path.into_inner();
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.git_release_get_by_tag_name(&session, user_id, &wk, &repo_name, &tag).await?)
+}
+
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/releases",
+    params(WkRepoPath),
+    request_body = CreateRelease,
+    responses((status = 201, body = ReleaseResponse)),
+    security(("session" = []))
+)]
+pub async fn create_release(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    body: web::Json<CreateRelease>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_created(service.git_release_create_by_name(&session, user_id, &path.wk, &path.repo, body.into_inner()).await?)
+}
+
+#[utoipa::path(
+    patch, path = "/api/v1/workspace/{wk}/repos/{repo}/releases/{id}",
+    params(ReleaseIdPath),
+    request_body = UpdateRelease,
+    responses((status = 200, body = ReleaseResponse)),
+    security(("session" = []))
+)]
+pub async fn update_release(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ReleaseIdPath>,
+    body: web::Json<UpdateRelease>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    ok_json(service.git_release_update_by_name(&session, user_id, &path.wk, &path.repo, path.id, body.into_inner()).await?)
+}
+
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/releases/{id}",
+    params(ReleaseIdPath),
+    responses((status = 204)),
+    security(("session" = []))
+)]
+pub async fn delete_release(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ReleaseIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    service.git_release_delete_by_name(&session, user_id, &path.wk, &path.repo, path.id).await?;
+    ok_empty()
+}
+
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/releases/tags/{tag}",
+    params(WkRepoPath, ("tag" = String, Path)),
+    responses((status = 204)),
+    security(("session" = []))
+)]
+pub async fn delete_release_by_tag(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, String, String)>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, repo_name, tag) = path.into_inner();
+    let user_id = session.user().ok_or(ApiError(service::error::AppError::Unauthorized))?;
+    service.git_release_delete_by_tag_name(&session, user_id, &wk, &repo_name, &tag).await?;
+    ok_empty()
+}
diff --git a/lib/api/src/git/repo.rs b/lib/api/src/git/repo.rs
new file mode 100644
index 0000000..c177df4
--- /dev/null
+++ b/lib/api/src/git/repo.rs
@@ -0,0 +1,203 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, Pagination,
+    git::repo::{RepoFilter, RepoResponse, TransferRepo, UpdateRepo},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        RepoFilter,
+        Pagination,
+    ),
+    responses(
+        (status = 200, body = Vec<RepoResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_repos(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    filter: web::Query<RepoFilter>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .repo_list(&session, &wk, filter.into_inner(), pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}",
+    params(WkRepoPath),
+    responses(
+        (status = 200, body = RepoResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Repo not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn get_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.repo_get(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/repos/{repo}",
+    params(WkRepoPath),
+    request_body = UpdateRepo,
+    responses(
+        (status = 200, body = RepoResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Repo not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<UpdateRepo>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_update(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/archive",
+    params(WkRepoPath),
+    responses(
+        (status = 200, body = RepoResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(("session" = []))
+)]
+pub async fn archive_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.repo_archive(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}",
+    params(WkRepoPath),
+    responses(
+        (status = 200, description = "Repo deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied - owner only"),
+    ),
+    security(("session" = []))
+)]
+pub async fn delete_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    service.repo_delete(&session, &wk, &repo).await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/transfer",
+    params(WkRepoPath),
+    request_body = TransferRepo,
+    responses(
+        (status = 200, body = RepoResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied - owner only"),
+        (status = 409, description = "Name conflict in target workspace"),
+    ),
+    security(("session" = []))
+)]
+pub async fn transfer_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<TransferRepo>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_transfer(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/topics",
+    params(WkRepoPath),
+    responses(
+        (status = 200, body = Vec<String>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn get_topics(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.repo_topics(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/topics",
+    params(WkRepoPath),
+    request_body = Vec<String>,
+    responses(
+        (status = 200, body = Vec<String>),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_topics(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    topics: web::Json<Vec<String>>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_update_topics(&session, &wk, &repo, topics.into_inner())
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/star.rs b/lib/api/src/git/star.rs
new file mode 100644
index 0000000..bb0375c
--- /dev/null
+++ b/lib/api/src/git/star.rs
@@ -0,0 +1,63 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/star",
+    params(WkRepoPath),
+    responses((status = 200, description = "Star/unstar result")),
+    security(("session" = []))
+)]
+pub async fn star_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_star(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/git/star",
+    params(WkRepoPath),
+    responses((status = 200, description = "Star/unstar result")),
+    security(("session" = []))
+)]
+pub async fn unstar_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_unstar(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/star",
+    params(WkRepoPath),
+    responses((status = 200, description = "Star status")),
+    security(("session" = []))
+)]
+pub async fn star_status(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_star_status(&session, &wk, &repo).await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/tag.rs b/lib/api/src/git/tag.rs
new file mode 100644
index 0000000..66e96b5
--- /dev/null
+++ b/lib/api/src/git/tag.rs
@@ -0,0 +1,170 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{AppService, Pagination};
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoTagPath {
+    pub wk: String,
+    pub repo: String,
+    pub name: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct TagListQuery {
+    #[serde(default)]
+    pub summary: bool,
+}
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct RenameTagBody {
+    pub new_name: String,
+}
+#[derive(Deserialize, utoipa::ToSchema)]
+pub struct UpdateTagMessageBody {
+    pub message: String,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/tags",
+    params(WkRepoPath, Pagination, TagListQuery),
+    responses(
+        (status = 200, description = "Tag list", body = dto::TagListResponseDto),
+        (status = 200, description = "Tag summary", body = dto::TagSummaryResponseDto),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_tags(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    pagination: web::Query<Pagination>,
+    query: web::Query<TagListQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    if query.summary {
+        let data: dto::TagSummaryResponseDto = service
+            .git_tag_summary(&session, &wk, &repo)
+            .await?
+            .into();
+        return ok_json(data);
+    }
+    let data: dto::TagListResponseDto = service
+        .git_tag_list(&session, &wk, &repo, pagination.into_inner())
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/tags/{name}",
+    params(WkRepoTagPath),
+    responses((status = 200, description = "Tag info", body = dto::TagInfoResponseDto)),
+    security(("session" = []))
+)]
+pub async fn tag_info(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoTagPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoTagPath { wk, repo, name } = path.into_inner();
+    let data: dto::TagInfoResponseDto = service
+        .git_tag_info(&session, &wk, &repo, name)
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/tags",
+    params(WkRepoPath),
+    request_body = Object, description = "TagInitParams { name, oid, message, tagger, force }",
+    responses((status = 200, description = "Tag created", body = dto::TagInitResponseDto)),
+    security(("session" = []))
+)]
+pub async fn init_tag(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<git::rpc::proto::TagInitParams>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data: dto::TagInitResponseDto = service
+        .git_tag_init(&session, &wk, &repo, params.into_inner())
+        .await?
+        .into();
+    ok_json(data)
+}
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/git/tags/{name}",
+    params(WkRepoTagPath),
+    responses((status = 200, description = "Tag deleted")),
+    security(("session" = []))
+)]
+pub async fn delete_tag(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoTagPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoTagPath { wk, repo, name } = path.into_inner();
+    let params = git::rpc::proto::TagDeleteParams { name };
+    let _ = service
+        .git_tag_delete(&session, &wk, &repo, params)
+        .await?;
+    ok_json(serde_json::json!({}))
+}
+#[utoipa::path(
+    patch, path = "/api/v1/workspace/{wk}/repos/{repo}/git/tags/{name}",
+    params(WkRepoTagPath),
+    request_body = Object,
+    responses(
+        (status = 200, description = "Tag renamed"),
+        (status = 200, description = "Tag message updated"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_tag(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoTagPath>,
+    body: web::Json<serde_json::Value>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoTagPath { wk, repo, name } = path.into_inner();
+    let body = body.into_inner();
+    if let Some(new_name) = body.get("new_name").and_then(|v| v.as_str()) {
+        let params = git::rpc::proto::TagRenameParams {
+            old_name: name,
+            new_name: new_name.to_string(),
+            force: false,
+        };
+        let _ = service
+            .git_tag_rename(&session, &wk, &repo, params)
+            .await?;
+        return ok_json(serde_json::json!({}));
+    }
+    let message = body
+        .get("message")
+        .and_then(|v| v.as_str())
+        .unwrap_or("")
+        .to_string();
+    let params = git::rpc::proto::TagUpdateMessageParams {
+        name,
+        message,
+        tagger: None,
+        force: false,
+    };
+    let data: dto::TagUpdateMessageResponseDto = service
+        .git_tag_update_message(&session, &wk, &repo, params)
+        .await?
+        .into();
+    ok_json(data)
+}
diff --git a/lib/api/src/git/tree.rs b/lib/api/src/git/tree.rs
new file mode 100644
index 0000000..ec25ffd
--- /dev/null
+++ b/lib/api/src/git/tree.rs
@@ -0,0 +1,119 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+use crate::git::dto;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoTreePath {
+    pub wk: String,
+    pub repo: String,
+    pub oid: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct TreeQuery {
+    pub path: Option<String>,
+    #[serde(default)]
+    pub last: bool,
+    #[serde(default)]
+    pub resolve: bool,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/trees/{oid}",
+    params(WkRepoTreePath, TreeQuery),
+    responses((status = 200, description = "Tree entries", body = dto::TreeEntriesResponseDto)),
+    security(("session" = []))
+)]
+pub async fn tree_entries(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoTreePath>,
+    query: web::Query<TreeQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoTreePath { wk, repo, oid } = path.into_inner();
+
+    if query.resolve {
+        let data: dto::ResolveTreeResponseDto = service
+            .git_resolve_tree(&session, &wk, &repo, oid)
+            .await?
+            .into();
+        return ok_json(data);
+    }
+
+    let base_path = query.path.clone().unwrap_or_default();
+    let data: dto::TreeEntriesResponseDto = service
+        .git_tree_entries(&session, &wk, &repo, oid, base_path, query.last)
+        .await?
+        .into();
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoTreeSubPath {
+    pub wk: String,
+    pub repo: String,
+    pub tree_oid: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct TreeEntryQuery {
+    pub path: String,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/trees/{tree_oid}/entries",
+    params(WkRepoTreeSubPath, TreeEntryQuery),
+    responses((status = 200, description = "Tree entry", body = dto::TreeEntryByPathResponseDto)),
+    security(("session" = []))
+)]
+pub async fn tree_entry_by_path(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoTreeSubPath>,
+    query: web::Query<TreeEntryQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoTreeSubPath { wk, repo, tree_oid } = path.into_inner();
+    let data: dto::TreeEntryByPathResponseDto = service
+        .git_tree_entry_by_path(&session, &wk, &repo, tree_oid, query.path.clone())
+        .await?
+        .into();
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoCommitPath {
+    pub wk: String,
+    pub repo: String,
+    pub oid: String,
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/commits/{oid}/tree",
+    params(WkRepoCommitPath, TreeEntryQuery),
+    responses((status = 200, description = "Tree entry", body = dto::TreeEntryByPathResponseDto)),
+    security(("session" = []))
+)]
+pub async fn tree_entry_by_path_from_commit(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoCommitPath>,
+    query: web::Query<TreeEntryQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoCommitPath { wk, repo, oid } = path.into_inner();
+    let data: dto::TreeEntryByPathResponseDto = service
+        .git_tree_entry_by_path_from_commit(&session, &wk, &repo, oid, query.path.clone())
+        .await?
+        .into();
+    ok_json(data)
+}
diff --git a/lib/api/src/git/watch.rs b/lib/api/src/git/watch.rs
new file mode 100644
index 0000000..c01cd96
--- /dev/null
+++ b/lib/api/src/git/watch.rs
@@ -0,0 +1,63 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::AppService;
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WkRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+#[utoipa::path(
+    post, path = "/api/v1/workspace/{wk}/repos/{repo}/git/watch",
+    params(WkRepoPath), request_body = Object, description = "WatchLevel {level: String}",
+    responses((status = 200, description = "Watch result")),
+    security(("session" = []))
+)]
+pub async fn watch_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    body: web::Json<serde_json::Value>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let level = body.get("level").and_then(|v| v.as_str()).map(String::from);
+    let data = service.git_repo_watch(&session, &wk, &repo, level).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete, path = "/api/v1/workspace/{wk}/repos/{repo}/git/watch",
+    params(WkRepoPath),
+    responses((status = 200, description = "Watch result")),
+    security(("session" = []))
+)]
+pub async fn unwatch_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_unwatch(&session, &wk, &repo).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get, path = "/api/v1/workspace/{wk}/repos/{repo}/git/watch",
+    params(WkRepoPath),
+    responses((status = 200, description = "Watch status")),
+    security(("session" = []))
+)]
+pub async fn watch_status(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service.git_repo_watch_status(&session, &wk, &repo).await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/git/webhook.rs b/lib/api/src/git/webhook.rs
new file mode 100644
index 0000000..40b0995
--- /dev/null
+++ b/lib/api/src/git/webhook.rs
@@ -0,0 +1,168 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, Pagination,
+    git::webhook::{
+        CreateWebhook, UpdateWebhook, WebhookDeliveryResponse, WebhookResponse,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+use super::repo::WkRepoPath;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct WebhookPath {
+    pub wk: String,
+    pub repo: String,
+    pub webhook_id: uuid::Uuid,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/webhooks",
+    params(WkRepoPath, Pagination),
+    responses(
+        (status = 200, body = Vec<WebhookResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_webhooks(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_webhook_list(&session, &wk, &repo, pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/webhooks",
+    params(WkRepoPath),
+    request_body = CreateWebhook,
+    responses(
+        (status = 200, body = WebhookResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_webhook(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WkRepoPath>,
+    params: web::Json<CreateWebhook>,
+) -> Result<HttpResponse, ApiError> {
+    let WkRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .repo_webhook_create(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/webhooks/{webhook_id}",
+    params(WebhookPath),
+    request_body = UpdateWebhook,
+    responses(
+        (status = 200, body = WebhookResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Webhook not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_webhook(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WebhookPath>,
+    params: web::Json<UpdateWebhook>,
+) -> Result<HttpResponse, ApiError> {
+    let WebhookPath {
+        wk,
+        repo,
+        webhook_id,
+    } = path.into_inner();
+    let data = service
+        .repo_webhook_update(
+            &session,
+            &wk,
+            &repo,
+            webhook_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/webhooks/{webhook_id}",
+    params(WebhookPath),
+    responses(
+        (status = 200, description = "Webhook deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Webhook not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn delete_webhook(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WebhookPath>,
+) -> Result<HttpResponse, ApiError> {
+    let WebhookPath {
+        wk,
+        repo,
+        webhook_id,
+    } = path.into_inner();
+    service
+        .repo_webhook_delete(&session, &wk, &repo, webhook_id)
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/webhooks/{webhook_id}/deliveries",
+    params(WebhookPath, Pagination),
+    responses(
+        (status = 200, body = Vec<WebhookDeliveryResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_deliveries(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<WebhookPath>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let WebhookPath {
+        wk,
+        repo,
+        webhook_id,
+    } = path.into_inner();
+    let data = service
+        .repo_webhook_deliveries(
+            &session,
+            &wk,
+            &repo,
+            webhook_id,
+            pagination.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/issues/assignee.rs b/lib/api/src/issues/assignee.rs
new file mode 100644
index 0000000..2822ff5
--- /dev/null
+++ b/lib/api/src/issues/assignee.rs
@@ -0,0 +1,75 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    issues::{assignee::AssignIssueUser, types::IssueAuthor},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct AssigneePath {
+    pub wk: String,
+    pub number: i64,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/assignees",
+    params(AssigneePath),
+    request_body = AssignIssueUser,
+    responses(
+        (status = 200, body = Vec<IssueAuthor>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn assign_user(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<AssigneePath>,
+    params: web::Json<AssignIssueUser>,
+) -> Result<HttpResponse, ApiError> {
+    let AssigneePath { wk, number } = path.into_inner();
+    let data = service
+        .issue_assign(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/assignees",
+    params(AssigneePath),
+    responses(
+        (status = 200, body = Vec<IssueAuthor>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn unassign_user(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<AssigneePath>,
+    query: web::Query<UnassignQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let AssigneePath { wk, number } = path.into_inner();
+    let data = service
+        .issue_unassign(&session, &wk, number, &query.username)
+        .await?;
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct UnassignQuery {
+    pub username: String,
+}
diff --git a/lib/api/src/issues/binding.rs b/lib/api/src/issues/binding.rs
new file mode 100644
index 0000000..7a2cdb9
--- /dev/null
+++ b/lib/api/src/issues/binding.rs
@@ -0,0 +1,141 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    issues::{
+        binding::{BindIssuePullRequest, BindIssueRepo},
+        types::{IssuePullRequestResponse, IssueRepoResponse},
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/repos",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    request_body = BindIssueRepo,
+    responses(
+        (status = 200, body = Vec<IssueRepoResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or repo not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn bind_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    params: web::Json<BindIssueRepo>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_bind_repo(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/repos",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, body = Vec<IssueRepoResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or repo not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn unbind_repo(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    query: web::Query<UnbindRepoQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_unbind_repo(&session, &wk, number, query.repo_id)
+        .await?;
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct UnbindRepoQuery {
+    pub repo_id: Uuid,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/pull-requests",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    request_body = BindIssuePullRequest,
+    responses(
+        (status = 200, body = Vec<IssuePullRequestResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or PR not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn bind_pull_request(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    params: web::Json<BindIssuePullRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_bind_pull_request(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/pull-requests",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, body = Vec<IssuePullRequestResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or PR not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn unbind_pull_request(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    query: web::Query<UnbindPrQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_unbind_pull_request(&session, &wk, number, query.pull_request_id)
+        .await?;
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct UnbindPrQuery {
+    pub pull_request_id: Uuid,
+}
diff --git a/lib/api/src/issues/comment.rs b/lib/api/src/issues/comment.rs
new file mode 100644
index 0000000..05f06c0
--- /dev/null
+++ b/lib/api/src/issues/comment.rs
@@ -0,0 +1,145 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    issues::{
+        comment::{CreateComment, UpdateComment},
+        types::IssueCommentResponse,
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct CommentPath {
+    pub wk: String,
+    pub number: i64,
+    pub comment_id: Uuid,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/comments",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    request_body = CreateComment,
+    responses(
+        (status = 200, body = IssueCommentResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn create_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    params: web::Json<CreateComment>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_comment_create(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/issues/{number}/comments",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, body = Vec<IssueCommentResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_comments(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service.issue_comment_list(&session, &wk, number).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/issues/{number}/comments/{comment_id}",
+    params(CommentPath),
+    request_body = UpdateComment,
+    responses(
+        (status = 200, body = IssueCommentResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Comment not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommentPath>,
+    params: web::Json<UpdateComment>,
+) -> Result<HttpResponse, ApiError> {
+    let CommentPath {
+        wk,
+        number,
+        comment_id,
+    } = path.into_inner();
+    let data = service
+        .issue_comment_update(
+            &session,
+            &wk,
+            number,
+            comment_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/comments/{comment_id}",
+    params(CommentPath),
+    responses(
+        (status = 200, description = "Comment deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Comment not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn delete_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommentPath>,
+) -> Result<HttpResponse, ApiError> {
+    let CommentPath {
+        wk,
+        number,
+        comment_id,
+    } = path.into_inner();
+    service
+        .issue_comment_delete(&session, &wk, number, comment_id)
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/issues/event.rs b/lib/api/src/issues/event.rs
new file mode 100644
index 0000000..d62af73
--- /dev/null
+++ b/lib/api/src/issues/event.rs
@@ -0,0 +1,35 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, issues::types::IssueEventResponse};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/issues/{number}/events",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, body = Vec<IssueEventResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_events(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service.issue_events(&session, &wk, number).await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/issues/issue.rs b/lib/api/src/issues/issue.rs
new file mode 100644
index 0000000..67b27f6
--- /dev/null
+++ b/lib/api/src/issues/issue.rs
@@ -0,0 +1,198 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, Pagination,
+    issues::{
+        issue::{CreateIssue, UpdateIssue},
+        types::{IssueFilter, IssueResponse},
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct IssuePath {
+    pub wk: String,
+    pub number: i64,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = CreateIssue,
+    responses(
+        (status = 200, body = IssueResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Workspace not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn create_issue(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<CreateIssue>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .issue_create(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/issues",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        IssueFilter,
+        Pagination,
+    ),
+    responses(
+        (status = 200, body = Vec<IssueResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_issues(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    filter: web::Query<IssueFilter>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .issue_list(&session, &wk, filter.into_inner(), pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/issues/{number}",
+    params(IssuePath),
+    responses(
+        (status = 200, body = IssueResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn get_issue(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<IssuePath>,
+) -> Result<HttpResponse, ApiError> {
+    let IssuePath { wk, number } = path.into_inner();
+    let data = service.issue_get(&session, &wk, number).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/issues/{number}",
+    params(IssuePath),
+    request_body = UpdateIssue,
+    responses(
+        (status = 200, body = IssueResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_issue(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<IssuePath>,
+    params: web::Json<UpdateIssue>,
+) -> Result<HttpResponse, ApiError> {
+    let IssuePath { wk, number } = path.into_inner();
+    let data = service
+        .issue_update(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}",
+    params(IssuePath),
+    responses(
+        (status = 200, description = "Issue deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn delete_issue(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<IssuePath>,
+) -> Result<HttpResponse, ApiError> {
+    let IssuePath { wk, number } = path.into_inner();
+    service.issue_delete(&session, &wk, number).await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/close",
+    params(IssuePath),
+    responses(
+        (status = 200, body = IssueResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn close_issue(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<IssuePath>,
+) -> Result<HttpResponse, ApiError> {
+    let IssuePath { wk, number } = path.into_inner();
+    let data = service.issue_close(&session, &wk, number).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/reopen",
+    params(IssuePath),
+    responses(
+        (status = 200, body = IssueResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn reopen_issue(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<IssuePath>,
+) -> Result<HttpResponse, ApiError> {
+    let IssuePath { wk, number } = path.into_inner();
+    let data = service.issue_reopen(&session, &wk, number).await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/issues/label.rs b/lib/api/src/issues/label.rs
new file mode 100644
index 0000000..f6f034a
--- /dev/null
+++ b/lib/api/src/issues/label.rs
@@ -0,0 +1,190 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    issues::{
+        label::{AddIssueLabel, CreateLabel, UpdateLabel},
+        types::LabelResponse,
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct LabelIdPath {
+    pub wk: String,
+    pub label_id: Uuid,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/labels",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = CreateLabel,
+    responses(
+        (status = 200, body = LabelResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn create_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<CreateLabel>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .label_create(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/labels",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 200, body = Vec<LabelResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_labels(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service.label_list(&session, &wk).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/labels/{label_id}",
+    params(LabelIdPath),
+    request_body = UpdateLabel,
+    responses(
+        (status = 200, body = LabelResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Label not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<LabelIdPath>,
+    params: web::Json<UpdateLabel>,
+) -> Result<HttpResponse, ApiError> {
+    let LabelIdPath { wk, label_id } = path.into_inner();
+    let data = service
+        .label_update(&session, &wk, label_id, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/labels/{label_id}",
+    params(LabelIdPath),
+    responses(
+        (status = 200, description = "Label deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Label not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn delete_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<LabelIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    let LabelIdPath { wk, label_id } = path.into_inner();
+    service.label_delete(&session, &wk, label_id).await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/labels",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    request_body = AddIssueLabel,
+    responses(
+        (status = 200, body = Vec<LabelResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or label not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn add_issue_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    params: web::Json<AddIssueLabel>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_add_label(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/labels",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, body = Vec<LabelResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or label not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn remove_issue_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    query: web::Query<RemoveLabelQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_remove_label(&session, &wk, number, query.label_id)
+        .await?;
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct RemoveLabelQuery {
+    pub label_id: Uuid,
+}
diff --git a/lib/api/src/issues/milestone.rs b/lib/api/src/issues/milestone.rs
new file mode 100644
index 0000000..8b4b790
--- /dev/null
+++ b/lib/api/src/issues/milestone.rs
@@ -0,0 +1,184 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    issues::{
+        milestone::{CreateMilestone, SetIssueMilestone, UpdateMilestone},
+        types::MilestoneResponse,
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct MilestoneIdPath {
+    pub wk: String,
+    pub milestone_id: Uuid,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/milestones",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = CreateMilestone,
+    responses(
+        (status = 200, body = MilestoneResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn create_milestone(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<CreateMilestone>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .milestone_create(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/milestones",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 200, body = Vec<MilestoneResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_milestones(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service.milestone_list(&session, &wk).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/milestones/{milestone_id}",
+    params(MilestoneIdPath),
+    request_body = UpdateMilestone,
+    responses(
+        (status = 200, body = MilestoneResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Milestone not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_milestone(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<MilestoneIdPath>,
+    params: web::Json<UpdateMilestone>,
+) -> Result<HttpResponse, ApiError> {
+    let MilestoneIdPath { wk, milestone_id } = path.into_inner();
+    let data = service
+        .milestone_update(&session, &wk, milestone_id, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/milestones/{milestone_id}",
+    params(MilestoneIdPath),
+    responses(
+        (status = 200, description = "Milestone deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Milestone not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn delete_milestone(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<MilestoneIdPath>,
+) -> Result<HttpResponse, ApiError> {
+    let MilestoneIdPath { wk, milestone_id } = path.into_inner();
+    service
+        .milestone_delete(&session, &wk, milestone_id)
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/milestone",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    request_body = SetIssueMilestone,
+    responses(
+        (status = 200, body = Option<MilestoneResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue or milestone not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn set_issue_milestone(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    params: web::Json<SetIssueMilestone>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_set_milestone(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/milestone",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, description = "Milestone cleared"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn clear_issue_milestone(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    service.issue_clear_milestone(&session, &wk, number).await?;
+    ok()
+}
diff --git a/lib/api/src/issues/mod.rs b/lib/api/src/issues/mod.rs
new file mode 100644
index 0000000..78a14d3
--- /dev/null
+++ b/lib/api/src/issues/mod.rs
@@ -0,0 +1,104 @@
+pub mod assignee;
+pub mod binding;
+pub mod comment;
+pub mod event;
+pub mod issue;
+pub mod label;
+pub mod milestone;
+pub mod reaction;
+
+use actix_web::{web, web::ServiceConfig};
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("")
+            .route(web::post().to(issue::create_issue))
+            .route(web::get().to(issue::list_issues)),
+    );
+    cfg.service(
+        web::resource("/{number}")
+            .route(web::get().to(issue::get_issue))
+            .route(web::put().to(issue::update_issue))
+            .route(web::delete().to(issue::delete_issue)),
+    );
+    cfg.service(
+        web::resource("/{number}/close")
+            .route(web::post().to(issue::close_issue)),
+    );
+    cfg.service(
+        web::resource("/{number}/reopen")
+            .route(web::post().to(issue::reopen_issue)),
+    );
+    cfg.service(
+        web::resource("/{number}/comments")
+            .route(web::get().to(comment::list_comments))
+            .route(web::post().to(comment::create_comment)),
+    );
+    cfg.service(
+        web::resource("/{number}/comments/{comment_id}")
+            .route(web::put().to(comment::update_comment))
+            .route(web::delete().to(comment::delete_comment)),
+    );
+    cfg.service(
+        web::resource("/{number}/assignees")
+            .route(web::post().to(assignee::assign_user))
+            .route(web::delete().to(assignee::unassign_user)),
+    );
+    cfg.service(
+        web::resource("/{number}/labels")
+            .route(web::post().to(label::add_issue_label))
+            .route(web::delete().to(label::remove_issue_label)),
+    );
+    cfg.service(
+        web::resource("/{number}/milestone")
+            .route(web::post().to(milestone::set_issue_milestone))
+            .route(web::delete().to(milestone::clear_issue_milestone)),
+    );
+    cfg.service(
+        web::resource("/{number}/repos")
+            .route(web::post().to(binding::bind_repo))
+            .route(web::delete().to(binding::unbind_repo)),
+    );
+    cfg.service(
+        web::resource("/{number}/pull-requests")
+            .route(web::post().to(binding::bind_pull_request))
+            .route(web::delete().to(binding::unbind_pull_request)),
+    );
+    cfg.service(
+        web::resource("/{number}/reactions")
+            .route(web::post().to(reaction::add_reaction))
+            .route(web::delete().to(reaction::remove_reaction)),
+    );
+    cfg.service(
+        web::resource("/{number}/comments/{comment_id}/reactions")
+            .route(web::post().to(reaction::add_comment_reaction))
+            .route(web::delete().to(reaction::remove_comment_reaction)),
+    );
+    cfg.service(
+        web::resource("/{number}/events")
+            .route(web::get().to(event::list_events)),
+    );
+}
+pub fn configure_labels(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("")
+            .route(web::get().to(label::list_labels))
+            .route(web::post().to(label::create_label)),
+    );
+    cfg.service(
+        web::resource("/{label_id}")
+            .route(web::put().to(label::update_label))
+            .route(web::delete().to(label::delete_label)),
+    );
+}
+pub fn configure_milestones(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("")
+            .route(web::get().to(milestone::list_milestones))
+            .route(web::post().to(milestone::create_milestone)),
+    );
+    cfg.service(
+        web::resource("/{milestone_id}")
+            .route(web::put().to(milestone::update_milestone))
+            .route(web::delete().to(milestone::delete_milestone)),
+    );
+}
diff --git a/lib/api/src/issues/reaction.rs b/lib/api/src/issues/reaction.rs
new file mode 100644
index 0000000..ab2859c
--- /dev/null
+++ b/lib/api/src/issues/reaction.rs
@@ -0,0 +1,152 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    issues::{reaction::AddReaction, types::IssueReactionResponse},
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize)]
+pub struct ReactionPath {
+    pub wk: String,
+    pub number: i64,
+    pub comment_id: Option<Uuid>,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/reactions",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    request_body = AddReaction,
+    responses(
+        (status = 200, body = Vec<IssueReactionResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Issue not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn add_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    params: web::Json<AddReaction>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_add_reaction(&session, &wk, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/reactions",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+    ),
+    responses(
+        (status = 200, body = Vec<IssueReactionResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn remove_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64)>,
+    query: web::Query<RemoveReactionQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number) = path.into_inner();
+    let data = service
+        .issue_remove_reaction(&session, &wk, number, &query.reaction)
+        .await?;
+    ok_json(data)
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct RemoveReactionQuery {
+    pub reaction: String,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/issues/{number}/comments/{comment_id}/reactions",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+        ("comment_id" = Uuid, Path, description = "Comment ID"),
+    ),
+    request_body = AddReaction,
+    responses(
+        (status = 200, body = Vec<IssueReactionResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Comment not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn add_comment_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64, Uuid)>,
+    params: web::Json<AddReaction>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number, comment_id) = path.into_inner();
+    let data = service
+        .issue_comment_add_reaction(
+            &session,
+            &wk,
+            number,
+            comment_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/issues/{number}/comments/{comment_id}/reactions",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("number" = i64, Path, description = "Issue number"),
+        ("comment_id" = Uuid, Path, description = "Comment ID"),
+    ),
+    responses(
+        (status = 200, body = Vec<IssueReactionResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn remove_comment_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<(String, i64, Uuid)>,
+    query: web::Query<RemoveReactionQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let (wk, number, comment_id) = path.into_inner();
+    let data = service
+        .issue_comment_remove_reaction(
+            &session,
+            &wk,
+            number,
+            comment_id,
+            &query.reaction,
+        )
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/lib.rs b/lib/api/src/lib.rs
new file mode 100644
index 0000000..df87920
--- /dev/null
+++ b/lib/api/src/lib.rs
@@ -0,0 +1,59 @@
+pub mod agent;
+pub mod ai;
+pub mod auth;
+pub mod channel;
+pub mod error;
+pub mod git;
+pub mod issues;
+pub mod openapi;
+pub mod pull_request;
+pub mod search;
+pub mod user;
+pub mod users;
+pub mod workspace;
+
+use actix_web::web::{self, ServiceConfig};
+
+pub fn configure(cfg: &mut ServiceConfig, channel_bus: channel::ChannelBus) {
+    cfg.service(
+        web::scope("/api/v1")
+            .configure(auth::configure)
+            .configure(user::configure)
+            .configure(users::configure)
+            .configure(ai::configure)
+            .configure(agent::configure)
+            .service(
+                web::scope("/workspace")
+                    .configure(workspace::configure)
+                    .service(
+                        web::scope("/{wk}")
+                            .configure(workspace::configure_wk)
+                            .service(
+                                web::scope("/repos")
+                                    .configure(git::configure)
+                                    .configure(pull_request::configure)
+                            )
+                            .service(
+                                web::scope("/issues")
+                                    .configure(issues::configure)
+                            )
+                            .service(
+                                web::scope("/labels")
+                                    .configure(issues::configure_labels)
+                            )
+                            .service(
+                                web::scope("/milestones")
+                                    .configure(issues::configure_milestones)
+                            )
+                    )
+            )
+            .service(
+                web::scope("/ws")
+                    .configure(|cfg| channel::configure(cfg, channel_bus)),
+            )
+            .service(
+                web::resource("/search")
+                    .route(web::get().to(search::search)),
+            )
+    );
+}
diff --git a/lib/api/src/openapi.rs b/lib/api/src/openapi.rs
new file mode 100644
index 0000000..da4109c
--- /dev/null
+++ b/lib/api/src/openapi.rs
@@ -0,0 +1,395 @@
+use utoipa::Modify;
+use utoipa::OpenApi;
+use utoipa::openapi::security::{
+    ApiKey, ApiKeyValue, SecurityRequirement, SecurityScheme,
+};
+
+#[derive(utoipa::OpenApi)]
+#[openapi(
+    info(
+        title = "GitDataAI API",
+        version = "1.0.0",
+        description = "GitDataAI platform REST API"
+    ),
+    tags(
+        (name = "auth", description = "Authentication & 2FA"),
+        (name = "user", description = "Current user settings & profile"),
+        (name = "users", description = "Public user info & relationships"),
+        (name = "workspace", description = "Workspace management"),
+        (name = "issues", description = "Issue tracking"),
+        (name = "pull_request", description = "Pull request operations"),
+        (name = "git", description = "Git repository operations"),
+        (name = "repos", description = "Repo management & configuration"),
+        (name = "ai", description = "AI model catalog"),
+        (name = "agent", description = "AI Agent sessions, conversations & streaming"),
+        (name = "channel", description = "Channel WebSocket & REST fallback"),
+        (name = "search", description = "Global search across workspaces, repos, channels, issues")
+    ),
+    paths(
+        crate::auth::captcha::captcha,
+        crate::auth::login::login,
+        crate::auth::logout::logout,
+        crate::auth::me::me,
+        crate::auth::register::register,
+        crate::auth::reset_pass::reset_password_request,
+        crate::auth::reset_pass::reset_password_verify,
+        crate::auth::rsa::rsa,
+        crate::auth::totp::enable_2fa,
+        crate::auth::totp::verify_2fa,
+        crate::auth::totp::disable_2fa,
+        crate::auth::totp::status_2fa,
+        crate::auth::totp::regenerate_backup_codes,
+        crate::auth::email::get_email,
+        crate::auth::email::email_change_request,
+        crate::auth::email::email_verify,
+        crate::user::config::user_config,
+        crate::user::accessibility::update_accessibility,
+        crate::user::appearance::update_appearance,
+        crate::user::notification::update_notification,
+        crate::user::privacy::update_privacy,
+        crate::user::profile::update_profile,
+        crate::user::profile::upload_avatar,
+        crate::user::access_token::list_access_tokens,
+        crate::user::access_token::create_access_token,
+        crate::user::access_token::update_access_token,
+        crate::user::access_token::revoke_access_token,
+        crate::user::sshkey::list_ssh_keys,
+        crate::user::sshkey::add_ssh_key,
+        crate::user::sshkey::update_ssh_key,
+        crate::user::sshkey::revoke_ssh_key,
+        crate::user::chpc::contribution_heatmap,
+        crate::user::chpc::invalidate_chpc_cache,
+        crate::users::summary::user_summary,
+        crate::users::public::user_public,
+        crate::users::chpc::user_chpc,
+        crate::users::relation::follow_user,
+        crate::users::relation::unfollow_user,
+        crate::users::relation::block_user,
+        crate::users::relation::unblock_user,
+        crate::users::relation::relation_status,
+        crate::users::relation::followers,
+        crate::users::relation::following,
+        crate::users::relation::blocked_list,
+        crate::users::relation::relation_counts,
+        crate::users::avatar::user_avatar,
+        crate::workspace::workspace::create_workspace,
+        crate::workspace::workspace::my_workspaces,
+        crate::workspace::workspace::get_workspace,
+        crate::workspace::workspace::update_workspace,
+        crate::workspace::workspace::get_avatar,
+        crate::workspace::workspace::upload_avatar,
+        crate::workspace::member::list_members,
+        crate::workspace::member::add_member,
+        crate::workspace::member::update_member,
+        crate::workspace::member::remove_member,
+        crate::workspace::group::list_groups,
+        crate::workspace::group::create_group,
+        crate::workspace::group::update_group,
+        crate::workspace::group::delete_group,
+        crate::workspace::group::add_group_member,
+        crate::workspace::group::remove_group_member,
+        crate::workspace::group::list_group_members,
+        crate::workspace::join::join_strategy,
+        crate::workspace::join::update_join_strategy,
+        crate::workspace::join::my_join_applies,
+        crate::workspace::join::apply_join,
+        crate::workspace::join::cancel_join,
+        crate::workspace::join::list_join_applies,
+        crate::workspace::join::approve_join,
+        crate::issues::issue::create_issue,
+        crate::issues::issue::list_issues,
+        crate::issues::issue::get_issue,
+        crate::issues::issue::update_issue,
+        crate::issues::issue::delete_issue,
+        crate::issues::issue::close_issue,
+        crate::issues::issue::reopen_issue,
+        crate::issues::comment::list_comments,
+        crate::issues::comment::create_comment,
+        crate::issues::comment::update_comment,
+        crate::issues::comment::delete_comment,
+        crate::issues::assignee::assign_user,
+        crate::issues::assignee::unassign_user,
+        crate::issues::label::add_issue_label,
+        crate::issues::label::remove_issue_label,
+        crate::issues::label::list_labels,
+        crate::issues::label::create_label,
+        crate::issues::label::update_label,
+        crate::issues::label::delete_label,
+        crate::issues::milestone::set_issue_milestone,
+        crate::issues::milestone::clear_issue_milestone,
+        crate::issues::milestone::list_milestones,
+        crate::issues::milestone::create_milestone,
+        crate::issues::milestone::update_milestone,
+        crate::issues::milestone::delete_milestone,
+        crate::issues::binding::bind_repo,
+        crate::issues::binding::unbind_repo,
+        crate::issues::binding::bind_pull_request,
+        crate::issues::binding::unbind_pull_request,
+        crate::issues::reaction::add_reaction,
+        crate::issues::reaction::remove_reaction,
+        crate::issues::reaction::add_comment_reaction,
+        crate::issues::reaction::remove_comment_reaction,
+        crate::issues::event::list_events,
+        crate::pull_request::pull_request::list_prs,
+        crate::pull_request::pull_request::create_pr,
+        crate::pull_request::pull_request::get_pr,
+        crate::pull_request::pull_request::update_pr,
+        crate::pull_request::pull_request::delete_pr,
+        crate::pull_request::merge::merge_pr,
+        crate::pull_request::merge::merge_analysis,
+        crate::pull_request::merge::update_branch,
+        crate::pull_request::assignee::assign_user,
+        crate::pull_request::assignee::unassign_user,
+        crate::pull_request::comment::list_comments,
+        crate::pull_request::comment::create_comment,
+        crate::pull_request::comment::update_comment,
+        crate::pull_request::comment::delete_comment,
+        crate::pull_request::label::add_label,
+        crate::pull_request::label::remove_label,
+        crate::pull_request::review::list_reviews,
+        crate::pull_request::review::create_review,
+        crate::pull_request::review::dismiss_review,
+        crate::pull_request::review::create_review_comment,
+        crate::pull_request::reaction::add_reaction,
+        crate::pull_request::reaction::remove_reaction,
+        crate::pull_request::reaction::add_comment_reaction,
+        crate::pull_request::reaction::remove_comment_reaction,
+        crate::git::init::create_repo,
+        crate::git::init::clone_repo,
+        crate::git::repo::list_repos,
+        crate::git::repo::get_repo,
+        crate::git::repo::update_repo,
+        crate::git::repo::delete_repo,
+        crate::git::repo::archive_repo,
+        crate::git::repo::transfer_repo,
+        crate::git::repo::get_topics,
+        crate::git::repo::update_topics,
+        crate::git::fork::create_fork,
+        crate::git::fork::list_forks,
+        crate::git::protect::list_protects,
+        crate::git::protect::create_protect,
+        crate::git::protect::update_protect,
+        crate::git::protect::delete_protect,
+        crate::git::webhook::list_webhooks,
+        crate::git::webhook::create_webhook,
+        crate::git::webhook::update_webhook,
+        crate::git::webhook::delete_webhook,
+        crate::git::webhook::list_deliveries,
+        crate::git::branch::list_branches,
+        crate::git::branch::fork_branch,
+        crate::git::branch::branch_info,
+        crate::git::branch::ahead_behind,
+        crate::git::branch::branch_upstream,
+        crate::git::branch::delete_branch,
+        crate::git::branch::rename_branch,
+        crate::git::commit::list_commits,
+        crate::git::commit::commit_info,
+        crate::git::commit::commit_history,
+        crate::git::commit::commit_walk,
+        crate::git::commit::cherry_pick,
+        crate::git::blob::blob_info,
+        crate::git::blob::blob_upload,
+        crate::git::blame::blame_file,
+        crate::git::tree::tree_entries,
+        crate::git::tree::tree_entry_by_path,
+        crate::git::tree::tree_entry_by_path_from_commit,
+        crate::git::diff::diff,
+        crate::git::tag::list_tags,
+        crate::git::tag::init_tag,
+        crate::git::tag::tag_info,
+        crate::git::tag::delete_tag,
+        crate::git::tag::update_tag,
+        crate::git::archive::archive,
+        crate::git::star::star_repo,
+        crate::git::star::unstar_repo,
+        crate::git::star::star_status,
+        crate::git::watch::watch_repo,
+        crate::git::watch::unwatch_repo,
+        crate::git::watch::watch_status,
+        crate::git::contributor::list_contributors,
+        crate::git::language::get_languages,
+        crate::git::readme::get_readme,
+        crate::git::readme::diff_branches,
+        crate::git::refs::list_refs,
+        crate::git::contents::get_contents,
+        crate::git::contents::create_contents,
+        crate::git::contents::update_contents,
+        crate::git::contents::delete_contents,
+        crate::git::compare::compare,
+        crate::git::release::list_releases,
+        crate::git::release::get_release,
+        crate::git::release::get_release_by_tag,
+        crate::git::release::create_release,
+        crate::git::release::update_release,
+        crate::git::release::delete_release,
+        crate::git::release::delete_release_by_tag,
+        crate::git::commit_status::list_statuses,
+        crate::git::commit_status::combined_status,
+        crate::git::commit_status::create_status,
+        crate::ai::model::list_models,
+        crate::ai::model::get_model,
+        crate::ai::model::list_versions,
+        crate::ai::model::get_card,
+        crate::ai::model::list_tags,
+        crate::ai::model::list_discussions,
+        crate::ai::model::list_likes,
+        crate::ai::provider::list_providers,
+        crate::ai::provider::get_provider,
+        crate::agent::session::create_session,
+        crate::agent::session::list_sessions,
+        crate::agent::session::get_session,
+        crate::agent::session::update_session,
+        crate::agent::session::delete_session,
+        crate::agent::conversation::list_all_conversations,
+        crate::agent::conversation::create_conversation,
+        crate::agent::conversation::list_conversations,
+        crate::agent::conversation::get_conversation,
+        crate::agent::conversation::update_conversation,
+        crate::agent::conversation::delete_conversation,
+        crate::agent::conversation::list_messages,
+        crate::agent::conversation::send_message,
+        crate::agent::conversation::stream_agent,
+        crate::channel::token::generate_token,
+        crate::channel::rest::ping,
+        crate::channel::rest::csrf_token,
+        crate::channel::rest_message::create_message,
+        crate::channel::rest_message::update_message,
+        crate::channel::rest_message::revoke_message,
+        crate::channel::rest_message::list_messages,
+        crate::channel::rest_message::messages_around,
+        crate::channel::rest_message::missed_messages,
+        crate::channel::rest_message::search,
+        crate::channel::rest_room::subscribe,
+        crate::channel::rest_room::unsubscribe,
+        crate::channel::rest_room::room_get,
+        crate::channel::rest_room::room_create,
+        crate::channel::rest_room::room_update,
+        crate::channel::rest_room::room_delete,
+        crate::channel::rest_room::access_grant,
+        crate::channel::rest_room::access_revoke,
+        crate::channel::rest_room::category_create,
+        crate::channel::rest_room::category_update,
+        crate::channel::rest_room::category_delete,
+        crate::channel::rest_interact::reaction_add,
+        crate::channel::rest_interact::reaction_remove,
+        crate::channel::rest_interact::thread_create,
+        crate::channel::rest_interact::thread_resolve,
+        crate::channel::rest_interact::thread_archive,
+        crate::channel::rest_interact::pin_add,
+        crate::channel::rest_interact::pin_remove,
+        crate::channel::rest_interact::draft_save,
+        crate::channel::rest_interact::draft_clear,
+        crate::channel::rest_interact::typing,
+        crate::channel::rest_member::read_receipt,
+        crate::channel::rest_member::dnd_update,
+        crate::channel::rest_member::notification_mark_read,
+        crate::channel::rest_member::notification_mark_all_read,
+        crate::channel::rest_member::notification_archive,
+        crate::channel::rest_member::presence_update,
+        crate::channel::rest_member::custom_status_update,
+        crate::channel::rest_member::invite_create,
+        crate::channel::rest_member::invite_accept,
+        crate::channel::rest_member::invite_revoke,
+        crate::channel::rest_member::ban_create,
+        crate::channel::rest_member::ban_remove,
+        crate::channel::rest_voice::voice_join,
+        crate::channel::rest_voice::voice_leave,
+        crate::channel::rest_voice::voice_mute,
+        crate::channel::rest_voice::voice_deaf,
+        crate::channel::rest_voice::screen_share,
+        crate::channel::rest_ai::ai_list,
+        crate::channel::rest_ai::ai_add,
+        crate::channel::rest_ai::ai_remove,
+        crate::channel::rest_ai::ai_stop,
+        crate::channel::rest_ai::user_summary,
+        crate::search::search,
+    ),
+    modifiers(&SecurityAddon)
+)]
+pub struct ApiDoc;
+
+struct SecurityAddon;
+
+impl Modify for SecurityAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        if let Some(components) = openapi.components.as_mut() {
+            components.add_security_scheme(
+                "session",
+                SecurityScheme::ApiKey(ApiKey::Cookie(ApiKeyValue::new("id"))),
+            );
+        }
+        openapi.security = Some(vec![SecurityRequirement::new(
+            "session",
+            Vec::<String>::new(),
+        )]);
+        openapi.info.license = None;
+        let remap = |t: &str| -> String {
+            if t.starts_with("crate::") {
+                let parts: Vec<&str> = t.split("::").collect();
+                parts.get(1).unwrap_or(&t).to_string()
+            } else {
+                t.to_string()
+            }
+        };
+        fn clean_tags(
+            op: &mut utoipa::openapi::path::Operation,
+            remap: impl Fn(&str) -> String,
+        ) {
+            if let Some(tags) = op.tags.as_mut() {
+                for t in tags.iter_mut() {
+                    *t = remap(t);
+                }
+                tags.dedup();
+            }
+        }
+        fn prefix_operation_id(op: &mut utoipa::openapi::path::Operation) {
+            if let Some(tags) = &op.tags {
+                if let Some(tag) = tags.first() {
+                    if let Some(id) = op.operation_id.as_mut() {
+                        if !id.starts_with(tag) {
+                            *id = format!("{}_{}", tag, id);
+                        }
+                    }
+                }
+            }
+        }
+        for (_path, item) in openapi.paths.paths.iter_mut() {
+            if let Some(op) = item.get.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.put.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.post.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.delete.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.patch.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.head.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.options.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+            if let Some(op) = item.trace.as_mut() {
+                clean_tags(op, remap);
+                prefix_operation_id(op);
+            }
+        }
+    }
+}
+
+pub fn openapi_json() -> String {
+    ApiDoc::openapi().to_pretty_json().unwrap()
+}
diff --git a/lib/api/src/pull_request/assignee.rs b/lib/api/src/pull_request/assignee.rs
new file mode 100644
index 0000000..f848bc7
--- /dev/null
+++ b/lib/api/src/pull_request/assignee.rs
@@ -0,0 +1,72 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, issues::types::IssueAuthor,
+    pull_request::assignee::AssignPrUser,
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct UnassignQuery {
+    pub username: String,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/assignees",
+    params(PrPath),
+    request_body = AssignPrUser,
+    responses(
+        (status = 200, body = Vec<IssueAuthor>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn assign_user(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<AssignPrUser>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_assign(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/assignees",
+    params(PrPath),
+    responses(
+        (status = 200, body = Vec<IssueAuthor>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn unassign_user(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    query: web::Query<UnassignQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_unassign(&session, &wk, &repo, number, &query.username)
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/pull_request/comment.rs b/lib/api/src/pull_request/comment.rs
new file mode 100644
index 0000000..367a6fb
--- /dev/null
+++ b/lib/api/src/pull_request/comment.rs
@@ -0,0 +1,145 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    pull_request::{
+        comment::{CreatePrComment, UpdatePrComment},
+        types::PullRequestCommentResponse,
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct CommentPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+    pub comment_id: Uuid,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/comments",
+    params(PrPath),
+    responses(
+        (status = 200, body = Vec<PullRequestCommentResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_comments(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_comment_list(&session, &wk, &repo, number)
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/comments",
+    params(PrPath),
+    request_body = CreatePrComment,
+    responses(
+        (status = 200, body = PullRequestCommentResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<CreatePrComment>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_comment_create(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/comments/{comment_id}",
+    params(CommentPath),
+    request_body = UpdatePrComment,
+    responses(
+        (status = 200, body = PullRequestCommentResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Only author can update"),
+        (status = 404, description = "Comment not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommentPath>,
+    params: web::Json<UpdatePrComment>,
+) -> Result<HttpResponse, ApiError> {
+    let CommentPath {
+        wk,
+        repo,
+        number,
+        comment_id,
+    } = path.into_inner();
+    let data = service
+        .pr_comment_update(
+            &session,
+            &wk,
+            &repo,
+            number,
+            comment_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/comments/{comment_id}",
+    params(CommentPath),
+    responses(
+        (status = 200, description = "Comment deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Comment not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn delete_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommentPath>,
+) -> Result<HttpResponse, ApiError> {
+    let CommentPath {
+        wk,
+        repo,
+        number: _,
+        comment_id,
+    } = path.into_inner();
+    service
+        .pr_comment_delete(&session, &wk, &repo, comment_id)
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/pull_request/label.rs b/lib/api/src/pull_request/label.rs
new file mode 100644
index 0000000..0d758bd
--- /dev/null
+++ b/lib/api/src/pull_request/label.rs
@@ -0,0 +1,72 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, issues::types::LabelResponse, pull_request::label::AddPrLabel,
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct RemoveLabelQuery {
+    pub label_id: Uuid,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/labels",
+    params(PrPath),
+    request_body = AddPrLabel,
+    responses(
+        (status = 200, body = Vec<LabelResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR or label not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn add_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<AddPrLabel>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_add_label(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/labels",
+    params(PrPath),
+    responses(
+        (status = 200, body = Vec<LabelResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR or label not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn remove_label(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    query: web::Query<RemoveLabelQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_remove_label(&session, &wk, &repo, number, query.label_id)
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/pull_request/merge.rs b/lib/api/src/pull_request/merge.rs
new file mode 100644
index 0000000..eb1933a
--- /dev/null
+++ b/lib/api/src/pull_request/merge.rs
@@ -0,0 +1,89 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    pull_request::{merge::MergePullRequest, types::PullRequestResponse},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/merge",
+    params(PrPath),
+    responses(
+        (status = 200, description = "Merge analysis result"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn merge_analysis(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_merge_analysis(&session, &wk, &repo, number)
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/merge",
+    params(PrPath),
+    request_body = MergePullRequest,
+    responses(
+        (status = 200, body = PullRequestResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn merge_pr(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<MergePullRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_merge(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/update-branch",
+    params(PrPath),
+    responses(
+        (status = 200, body = PullRequestResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_branch(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_update_branch(&session, &wk, &repo, number)
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/pull_request/mod.rs b/lib/api/src/pull_request/mod.rs
new file mode 100644
index 0000000..5d84f91
--- /dev/null
+++ b/lib/api/src/pull_request/mod.rs
@@ -0,0 +1,78 @@
+pub mod assignee;
+pub mod comment;
+pub mod label;
+pub mod merge;
+pub mod pull_request;
+pub mod reaction;
+pub mod review;
+
+use actix_web::{web, web::ServiceConfig};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::scope("/{repo}/pull-requests")
+            .service(
+                web::resource("")
+                    .route(web::get().to(pull_request::list_prs))
+                    .route(web::post().to(pull_request::create_pr)),
+            )
+            .service(
+                web::resource("/{number}")
+                    .route(web::get().to(pull_request::get_pr))
+                    .route(web::patch().to(pull_request::update_pr))
+                    .route(web::delete().to(pull_request::delete_pr)),
+            )
+            .service(
+                web::resource("/{number}/merge")
+                    .route(web::get().to(merge::merge_analysis))
+                    .route(web::post().to(merge::merge_pr)),
+            )
+            .service(
+                web::resource("/{number}/update-branch")
+                    .route(web::post().to(merge::update_branch)),
+            )
+            .service(
+                web::resource("/{number}/assignees")
+                    .route(web::post().to(assignee::assign_user))
+                    .route(web::delete().to(assignee::unassign_user)),
+            )
+            .service(
+                web::resource("/{number}/comments")
+                    .route(web::get().to(comment::list_comments))
+                    .route(web::post().to(comment::create_comment)),
+            )
+            .service(
+                web::resource("/{number}/comments/{comment_id}")
+                    .route(web::put().to(comment::update_comment))
+                    .route(web::delete().to(comment::delete_comment)),
+            )
+            .service(
+                web::resource("/{number}/labels")
+                    .route(web::post().to(label::add_label))
+                    .route(web::delete().to(label::remove_label)),
+            )
+            .service(
+                web::resource("/{number}/reviews")
+                    .route(web::get().to(review::list_reviews))
+                    .route(web::post().to(review::create_review)),
+            )
+            .service(
+                web::resource("/{number}/reviews/{review_id}/dismiss")
+                    .route(web::post().to(review::dismiss_review)),
+            )
+            .service(
+                web::resource("/{number}/review-comments")
+                    .route(web::post().to(review::create_review_comment)),
+            )
+            .service(
+                web::resource("/{number}/reactions")
+                    .route(web::post().to(reaction::add_reaction))
+                    .route(web::delete().to(reaction::remove_reaction)),
+            )
+            .service(
+                web::resource("/{number}/comments/{comment_id}/reactions")
+                    .route(web::post().to(reaction::add_comment_reaction))
+                    .route(web::delete().to(reaction::remove_comment_reaction)),
+            ),
+    );
+}
diff --git a/lib/api/src/pull_request/pull_request.rs b/lib/api/src/pull_request/pull_request.rs
new file mode 100644
index 0000000..16b444d
--- /dev/null
+++ b/lib/api/src/pull_request/pull_request.rs
@@ -0,0 +1,160 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, Pagination,
+    pull_request::{
+        pull_request::{CreatePullRequest, UpdatePullRequest},
+        types::{PullRequestFilter, PullRequestResponse},
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrRepoPath {
+    pub wk: String,
+    pub repo: String,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("repo" = String, Path, description = "Repo name"),
+    ),
+    request_body = CreatePullRequest,
+    responses(
+        (status = 200, body = PullRequestResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Repo not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_pr(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrRepoPath>,
+    params: web::Json<CreatePullRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let PrRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .pr_create(&session, &wk, &repo, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ("repo" = String, Path, description = "Repo name"),
+        PullRequestFilter,
+        Pagination,
+    ),
+    responses(
+        (status = 200, body = Vec<PullRequestResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_prs(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrRepoPath>,
+    filter: web::Query<PullRequestFilter>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let PrRepoPath { wk, repo } = path.into_inner();
+    let data = service
+        .pr_list(
+            &session,
+            &wk,
+            &repo,
+            filter.into_inner(),
+            pagination.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}",
+    params(PrPath),
+    responses(
+        (status = 200, body = PullRequestResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn get_pr(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service.pr_get(&session, &wk, &repo, number).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    patch,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}",
+    params(PrPath),
+    request_body = UpdatePullRequest,
+    responses(
+        (status = 200, body = PullRequestResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Only author can update"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn update_pr(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<UpdatePullRequest>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_update(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}",
+    params(PrPath),
+    responses(
+        (status = 200, description = "PR deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn delete_pr(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    service.pr_delete(&session, &wk, &repo, number).await?;
+    ok()
+}
diff --git a/lib/api/src/pull_request/reaction.rs b/lib/api/src/pull_request/reaction.rs
new file mode 100644
index 0000000..6a5ca4c
--- /dev/null
+++ b/lib/api/src/pull_request/reaction.rs
@@ -0,0 +1,155 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    pull_request::{
+        reaction::AddPrReaction, types::PullRequestReactionResponse,
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct RemoveReactionQuery {
+    pub reaction_id: Uuid,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct CommentReactionPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+    pub comment_id: Uuid,
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/reactions",
+    params(PrPath),
+    request_body = AddPrReaction,
+    responses(
+        (status = 200, body = PullRequestReactionResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn add_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<AddPrReaction>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_add_reaction(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/reactions",
+    params(PrPath),
+    responses(
+        (status = 200, description = "Reaction removed"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn remove_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    query: web::Query<RemoveReactionQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    service
+        .pr_remove_reaction(&session, &wk, &repo, number, query.reaction_id)
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/comments/{comment_id}/reactions",
+    params(CommentReactionPath),
+    request_body = AddPrReaction,
+    responses(
+        (status = 200, body = PullRequestReactionResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Comment not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn add_comment_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommentReactionPath>,
+    params: web::Json<AddPrReaction>,
+) -> Result<HttpResponse, ApiError> {
+    let CommentReactionPath {
+        wk,
+        repo,
+        number,
+        comment_id,
+    } = path.into_inner();
+    let data = service
+        .pr_comment_add_reaction(
+            &session,
+            &wk,
+            &repo,
+            number,
+            comment_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/comments/{comment_id}/reactions",
+    params(CommentReactionPath),
+    responses(
+        (status = 200, description = "Reaction removed"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn remove_comment_reaction(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<CommentReactionPath>,
+    query: web::Query<RemoveReactionQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let CommentReactionPath {
+        wk,
+        repo,
+        number,
+        comment_id: _,
+    } = path.into_inner();
+    service
+        .pr_comment_remove_reaction(
+            &session,
+            &wk,
+            &repo,
+            number,
+            query.reaction_id,
+        )
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/pull_request/review.rs b/lib/api/src/pull_request/review.rs
new file mode 100644
index 0000000..fa22156
--- /dev/null
+++ b/lib/api/src/pull_request/review.rs
@@ -0,0 +1,146 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    pull_request::{
+        review::{CreatePrReview, CreatePrReviewComment, DismissPrReview},
+        types::{PullRequestReviewCommentResponse, PullRequestReviewResponse},
+    },
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct PrPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct DismissPath {
+    pub wk: String,
+    pub repo: String,
+    pub number: i64,
+    pub review_id: Uuid,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/reviews",
+    params(PrPath),
+    responses(
+        (status = 200, body = Vec<PullRequestReviewResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("session" = []))
+)]
+pub async fn list_reviews(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service.pr_review_list(&session, &wk, &repo, number).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/reviews",
+    params(PrPath),
+    request_body = CreatePrReview,
+    responses(
+        (status = 200, body = PullRequestReviewResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_review(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<CreatePrReview>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_review_create(&session, &wk, &repo, number, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/reviews/{review_id}/dismiss",
+    params(DismissPath),
+    request_body = DismissPrReview,
+    responses(
+        (status = 200, description = "Review dismissed"),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Review not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn dismiss_review(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<DismissPath>,
+    params: web::Json<DismissPrReview>,
+) -> Result<HttpResponse, ApiError> {
+    let DismissPath {
+        wk,
+        repo,
+        number,
+        review_id,
+    } = path.into_inner();
+    service
+        .pr_review_dismiss(
+            &session,
+            &wk,
+            &repo,
+            number,
+            review_id,
+            params.into_inner(),
+        )
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/repos/{repo}/pull-requests/{number}/review-comments",
+    params(PrPath),
+    request_body = CreatePrReviewComment,
+    responses(
+        (status = 200, body = PullRequestReviewCommentResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "PR not found"),
+    ),
+    security(("session" = []))
+)]
+pub async fn create_review_comment(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<PrPath>,
+    params: web::Json<CreatePrReviewComment>,
+) -> Result<HttpResponse, ApiError> {
+    let PrPath { wk, repo, number } = path.into_inner();
+    let data = service
+        .pr_review_comment_create(
+            &session,
+            &wk,
+            &repo,
+            number,
+            None,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/search.rs b/lib/api/src/search.rs
new file mode 100644
index 0000000..2dca0cc
--- /dev/null
+++ b/lib/api/src/search.rs
@@ -0,0 +1,259 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+use crate::error::ApiError;
+use crate::channel::ChannelBus;
+use service::AppService;
+use session::Session;
+
+#[derive(Debug, serde::Deserialize, utoipa::IntoParams)]
+pub struct SearchQuery {
+    pub q: Option<String>,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct SearchResponse {
+    pub workspaces: SearchGroup<WorkspaceHit>,
+    pub repos: SearchGroup<RepoHit>,
+    pub rooms: SearchGroup<RoomHit>,
+    pub issues: SearchGroup<IssueHit>,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct SearchGroup<T: Serialize> {
+    pub items: Vec<T>,
+    pub total: usize,
+    pub has_more: bool,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct WorkspaceHit {
+    pub name: String,
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct RepoHit {
+    pub name: String,
+    pub workspace: String,
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct RoomHit {
+    pub id: String,
+    pub name: String,
+    pub workspace: String,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct IssueHit {
+    pub number: i32,
+    pub title: String,
+    pub state: String,
+    pub workspace: String,
+}
+
+const MAX_PER_GROUP: usize = 10;
+
+fn session_user(session: &Session) -> Result<uuid::Uuid, ApiError> {
+    session
+        .user()
+        .ok_or(ApiError(service::error::AppError::Unauthorized))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/search",
+    params(SearchQuery),
+    responses((status = 200, body = SearchResponse)),
+    security(("session" = [])),
+    tag = "search",
+)]
+pub async fn search(
+    session: Session,
+    service: web::Data<AppService>,
+    bus: web::Data<ChannelBus>,
+    query: web::Query<SearchQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let user_id = session_user(&session)?;
+    let q = query.q.as_deref().unwrap_or("").trim().to_lowercase();
+
+    let workspaces = search_workspaces(&service, user_id, &q).await?;
+    let repos = search_repos(&service, user_id, &q).await?;
+    let rooms = search_rooms(&bus, user_id, &q).await?;
+    let issues = search_issues(&service, user_id, &q).await?;
+
+    Ok(HttpResponse::Ok().json(SearchResponse {
+        workspaces,
+        repos,
+        rooms,
+        issues,
+    }))
+}
+
+async fn search_workspaces(
+    service: &AppService,
+    user_id: uuid::Uuid,
+    q: &str,
+) -> Result<SearchGroup<WorkspaceHit>, ApiError> {
+    let all: Vec<WorkspaceHit> = service
+        .workspace_my_inner(user_id)
+        .await?
+        .into_iter()
+        .map(|(name, desc)| WorkspaceHit {
+            name,
+            description: desc,
+        })
+        .collect();
+
+    let filtered: Vec<WorkspaceHit> = if q.is_empty() {
+        all
+    } else {
+        all.into_iter()
+            .filter(|w| {
+                w.name.to_lowercase().contains(q)
+                    || w.description
+                        .as_deref()
+                        .unwrap_or("")
+                        .to_lowercase()
+                        .contains(q)
+            })
+            .collect()
+    };
+
+    Ok(group_result(filtered))
+}
+
+async fn search_repos(
+    service: &AppService,
+    user_id: uuid::Uuid,
+    q: &str,
+) -> Result<SearchGroup<RepoHit>, ApiError> {
+    let workspaces: Vec<String> = service
+        .workspace_my_inner(user_id)
+        .await?
+        .into_iter()
+        .map(|(name, _)| name)
+        .collect();
+
+    let mut all: Vec<RepoHit> = Vec::new();
+    for wk in &workspaces {
+        if let Ok(repos) = service.repo_list_inner(wk).await {
+            for (name, desc) in repos {
+                all.push(RepoHit {
+                    name,
+                    workspace: wk.clone(),
+                    description: desc,
+                });
+            }
+        }
+    }
+
+    let filtered: Vec<RepoHit> = if q.is_empty() {
+        all
+    } else {
+        let q = q;
+        all.into_iter()
+            .filter(|r| {
+                format!(
+                    "{} {} {}",
+                    r.workspace,
+                    r.name,
+                    r.description.as_deref().unwrap_or("")
+                )
+                .to_lowercase()
+                .contains(q)
+            })
+            .collect()
+    };
+
+    Ok(group_result(filtered))
+}
+
+async fn search_rooms(
+    bus: &ChannelBus,
+    user_id: uuid::Uuid,
+    q: &str,
+) -> Result<SearchGroup<RoomHit>, ApiError> {
+    let rooms = bus
+        .list_user_rooms(user_id)
+        .await
+        .map_err(|e| {
+            ApiError(service::error::AppError::InternalServerError(
+                e.to_string(),
+            ))
+        })?;
+
+    let all: Vec<RoomHit> = rooms
+        .into_iter()
+        .map(|r| RoomHit {
+            id: r.id.to_string(),
+            name: r.name,
+            workspace: r.workspace_id.to_string(),
+        })
+        .collect();
+
+    let filtered: Vec<RoomHit> = if q.is_empty() {
+        all
+    } else {
+        all.into_iter()
+            .filter(|r| r.name.to_lowercase().contains(q))
+            .collect()
+    };
+
+    Ok(group_result(filtered))
+}
+
+async fn search_issues(
+    service: &AppService,
+    user_id: uuid::Uuid,
+    q: &str,
+) -> Result<SearchGroup<IssueHit>, ApiError> {
+    let workspaces: Vec<String> = service
+        .workspace_my_inner(user_id)
+        .await?
+        .into_iter()
+        .map(|(name, _)| name)
+        .collect();
+
+    let mut all: Vec<IssueHit> = Vec::new();
+    for wk in &workspaces {
+        if let Ok(issues) = service.issue_list_inner(wk).await {
+            for (number, title, state) in issues {
+                all.push(IssueHit {
+                    number,
+                    title,
+                    state,
+                    workspace: wk.clone(),
+                });
+            }
+        }
+    }
+
+    let filtered: Vec<IssueHit> = if q.is_empty() {
+        all
+    } else {
+        all.into_iter()
+            .filter(|i| {
+                format!("#{} {}", i.number, i.title)
+                    .to_lowercase()
+                    .contains(q)
+            })
+            .collect()
+    };
+
+    Ok(group_result(filtered))
+}
+
+fn group_result<T: Serialize>(mut items: Vec<T>) -> SearchGroup<T> {
+    let total = items.len();
+    let has_more = total > MAX_PER_GROUP;
+    items.truncate(MAX_PER_GROUP);
+    SearchGroup {
+        items,
+        total,
+        has_more,
+    }
+}
diff --git a/lib/api/src/user/access_token.rs b/lib/api/src/user/access_token.rs
new file mode 100644
index 0000000..4a1c75e
--- /dev/null
+++ b/lib/api/src/user/access_token.rs
@@ -0,0 +1,106 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::access_token::{
+        CreateUserAccessToken, CreatedUserAccessToken, UpdateUserAccessToken,
+        UserAccessToken,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/user/access-tokens",
+    responses(
+        (status = 200, body = Vec<UserAccessToken>)
+    ),
+    tag = "user"
+)]
+pub async fn list_access_tokens(
+    service: web::Data<AppService>,
+    session: Session,
+) -> Result<HttpResponse, ApiError> {
+    let tokens = service.user_access_tokens(&session).await?;
+    ok_json(tokens)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/user/access-tokens",
+    request_body = CreateUserAccessToken,
+    responses(
+        (status = 200, body = CreatedUserAccessToken)
+    ),
+    tag = "user"
+)]
+pub async fn create_access_token(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<CreateUserAccessToken>,
+) -> Result<HttpResponse, ApiError> {
+    let token = service
+        .user_create_access_token(&session, body.into_inner())
+        .await?;
+    ok_json(token)
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/access-tokens/{id}",
+    request_body = UpdateUserAccessToken,
+    responses(
+        (status = 200, body = UserAccessToken)
+    ),
+    params(
+        ("id" = i64, Path, description = "Access token ID")
+    ),
+    tag = "user"
+)]
+pub async fn update_access_token(
+    service: web::Data<AppService>,
+    session: Session,
+    token_id: web::Path<i64>,
+    body: web::Json<UpdateUserAccessToken>,
+) -> Result<HttpResponse, ApiError> {
+    let token = service
+        .user_update_access_token(
+            &session,
+            token_id.into_inner(),
+            body.into_inner(),
+        )
+        .await?;
+    ok_json(token)
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/user/access-tokens/{id}",
+    responses(
+        (status = 200)
+    ),
+    params(
+        ("id" = i64, Path, description = "Access token ID")
+    ),
+    tag = "user"
+)]
+pub async fn revoke_access_token(
+    service: web::Data<AppService>,
+    session: Session,
+    token_id: web::Path<i64>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .user_revoke_access_token(&session, token_id.into_inner())
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/user/accessibility.rs b/lib/api/src/user/accessibility.rs
new file mode 100644
index 0000000..bf80ec1
--- /dev/null
+++ b/lib/api/src/user/accessibility.rs
@@ -0,0 +1,35 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::accessibility::{
+        UpdateUserAccessibilityConfig, UserAccessibilityConfig,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/config/accessibility",
+    request_body = UpdateUserAccessibilityConfig,
+    responses(
+        (status = 200, body = UserAccessibilityConfig)
+    ),
+    tag = "user"
+)]
+pub async fn update_accessibility(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<UpdateUserAccessibilityConfig>,
+) -> Result<HttpResponse, ApiError> {
+    let config = service
+        .user_update_accessibility_config(&session, body.into_inner())
+        .await?;
+    ok_json(config)
+}
diff --git a/lib/api/src/user/appearance.rs b/lib/api/src/user/appearance.rs
new file mode 100644
index 0000000..cf809f0
--- /dev/null
+++ b/lib/api/src/user/appearance.rs
@@ -0,0 +1,33 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::appearance::{UpdateUserAppearanceConfig, UserAppearanceConfig},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/config/appearance",
+    request_body = UpdateUserAppearanceConfig,
+    responses(
+        (status = 200, body = UserAppearanceConfig)
+    ),
+    tag = "user"
+)]
+pub async fn update_appearance(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<UpdateUserAppearanceConfig>,
+) -> Result<HttpResponse, ApiError> {
+    let config = service
+        .user_update_appearance_config(&session, body.into_inner())
+        .await?;
+    ok_json(config)
+}
diff --git a/lib/api/src/user/chpc.rs b/lib/api/src/user/chpc.rs
new file mode 100644
index 0000000..e495384
--- /dev/null
+++ b/lib/api/src/user/chpc.rs
@@ -0,0 +1,53 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::chpc::{ContributionHeatmapQuery, ContributionHeatmapResponse},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/user/contribution-heatmap",
+    params(
+        ContributionHeatmapQuery
+    ),
+    responses(
+        (status = 200, body = ContributionHeatmapResponse)
+    ),
+    tag = "user"
+)]
+pub async fn contribution_heatmap(
+    service: web::Data<AppService>,
+    session: Session,
+    query: web::Query<ContributionHeatmapQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let response = service.user_chpc(&session, query.into_inner()).await?;
+    ok_json(response)
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/user/contribution-heatmap/cache",
+    responses(
+        (status = 200)
+    ),
+    tag = "user"
+)]
+pub async fn invalidate_chpc_cache(
+    service: web::Data<AppService>,
+    session: Session,
+) -> Result<HttpResponse, ApiError> {
+    service.user_invalidate_chpc_cache(&session).await?;
+    ok()
+}
diff --git a/lib/api/src/user/config.rs b/lib/api/src/user/config.rs
new file mode 100644
index 0000000..a484e56
--- /dev/null
+++ b/lib/api/src/user/config.rs
@@ -0,0 +1,26 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, user::config::UserConfigResponse};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/user/config",
+    responses(
+        (status = 200, body = UserConfigResponse)
+    ),
+    tag = "user"
+)]
+pub async fn user_config(
+    service: web::Data<AppService>,
+    session: Session,
+) -> Result<HttpResponse, ApiError> {
+    let config = service.user_config(&session).await?;
+    ok_json(config)
+}
diff --git a/lib/api/src/user/mod.rs b/lib/api/src/user/mod.rs
new file mode 100644
index 0000000..4165893
--- /dev/null
+++ b/lib/api/src/user/mod.rs
@@ -0,0 +1,77 @@
+pub mod access_token;
+pub mod accessibility;
+pub mod appearance;
+pub mod chpc;
+pub mod config;
+pub mod notification;
+pub mod privacy;
+pub mod profile;
+pub mod sshkey;
+
+use actix_web::{web, web::ServiceConfig};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::scope("/user")
+            .service(
+                web::resource("/notifications")
+                    .route(web::get().to(notification::list_notifications)),
+            )
+            .service(
+                web::resource("/config")
+                    .route(web::get().to(config::user_config)),
+            )
+            .service(
+                web::resource("/config/accessibility")
+                    .route(web::put().to(accessibility::update_accessibility)),
+            )
+            .service(
+                web::resource("/config/appearance")
+                    .route(web::put().to(appearance::update_appearance)),
+            )
+            .service(
+                web::resource("/config/notification")
+                    .route(web::put().to(notification::update_notification)),
+            )
+            .service(
+                web::resource("/config/privacy")
+                    .route(web::put().to(privacy::update_privacy)),
+            )
+            .service(
+                web::resource("/config/profile")
+                    .route(web::put().to(profile::update_profile)),
+            )
+            .service(
+                web::resource("/avatar")
+                    .route(web::post().to(profile::upload_avatar)),
+            )
+            .service(
+                web::resource("/access-tokens")
+                    .route(web::get().to(access_token::list_access_tokens))
+                    .route(web::post().to(access_token::create_access_token)),
+            )
+            .service(
+                web::resource("/access-tokens/{id}")
+                    .route(web::put().to(access_token::update_access_token))
+                    .route(web::delete().to(access_token::revoke_access_token)),
+            )
+            .service(
+                web::resource("/ssh-keys")
+                    .route(web::get().to(sshkey::list_ssh_keys))
+                    .route(web::post().to(sshkey::add_ssh_key)),
+            )
+            .service(
+                web::resource("/ssh-keys/{id}")
+                    .route(web::put().to(sshkey::update_ssh_key))
+                    .route(web::delete().to(sshkey::revoke_ssh_key)),
+            )
+            .service(
+                web::resource("/contribution-heatmap")
+                    .route(web::get().to(chpc::contribution_heatmap)),
+            )
+            .service(
+                web::resource("/contribution-heatmap/cache")
+                    .route(web::delete().to(chpc::invalidate_chpc_cache)),
+            ),
+    );
+}
diff --git a/lib/api/src/user/notification.rs b/lib/api/src/user/notification.rs
new file mode 100644
index 0000000..813fdef
--- /dev/null
+++ b/lib/api/src/user/notification.rs
@@ -0,0 +1,56 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService, Pagination,
+    user::notification::{
+        AppNotificationItem, UpdateUserNotificationConfig,
+        UserNotificationConfig,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/user/notifications",
+    params(Pagination),
+    responses(
+        (status = 200, body = Vec<AppNotificationItem>)
+    ),
+    tag = "user"
+)]
+pub async fn list_notifications(
+    service: web::Data<AppService>,
+    session: Session,
+    query: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let notifications = service
+        .list_notifications(&session, query.into_inner())
+        .await?;
+    ok_json(notifications)
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/config/notification",
+    request_body = UpdateUserNotificationConfig,
+    responses(
+        (status = 200, body = UserNotificationConfig)
+    ),
+    tag = "user"
+)]
+pub async fn update_notification(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<UpdateUserNotificationConfig>,
+) -> Result<HttpResponse, ApiError> {
+    let config = service
+        .user_update_notification_config(&session, body.into_inner())
+        .await?;
+    ok_json(config)
+}
diff --git a/lib/api/src/user/privacy.rs b/lib/api/src/user/privacy.rs
new file mode 100644
index 0000000..e65d5aa
--- /dev/null
+++ b/lib/api/src/user/privacy.rs
@@ -0,0 +1,33 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::privacy::{UpdateUserPrivacyConfig, UserPrivacyConfig},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/config/privacy",
+    request_body = UpdateUserPrivacyConfig,
+    responses(
+        (status = 200, body = UserPrivacyConfig)
+    ),
+    tag = "user"
+)]
+pub async fn update_privacy(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<UpdateUserPrivacyConfig>,
+) -> Result<HttpResponse, ApiError> {
+    let config = service
+        .user_update_privacy_config(&session, body.into_inner())
+        .await?;
+    ok_json(config)
+}
diff --git a/lib/api/src/user/profile.rs b/lib/api/src/user/profile.rs
new file mode 100644
index 0000000..87e287e
--- /dev/null
+++ b/lib/api/src/user/profile.rs
@@ -0,0 +1,61 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::profile::{AvatarUploadResponse, UpdateUserProfileConfig, UserProfileConfig},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/config/profile",
+    request_body = UpdateUserProfileConfig,
+    responses(
+        (status = 200, body = UserProfileConfig)
+    ),
+    tag = "user"
+)]
+pub async fn update_profile(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<UpdateUserProfileConfig>,
+) -> Result<HttpResponse, ApiError> {
+    let config = service
+        .user_update_profile_config(&session, body.into_inner())
+        .await?;
+    ok_json(config)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/user/avatar",
+    request_body(content = Vec<u8>, content_type = "image/*"),
+    responses(
+        (status = 200, body = AvatarUploadResponse),
+        (status = 400, description = "Invalid file type or size")
+    ),
+    tag = "user"
+)]
+pub async fn upload_avatar(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Bytes,
+    req: HttpRequest,
+) -> Result<HttpResponse, ApiError> {
+    let content_type = req
+        .headers()
+        .get("content-type")
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("application/octet-stream");
+
+    let response = service
+        .user_upload_avatar(&session, body.to_vec(), content_type)
+        .await?;
+    ok_json(response)
+}
diff --git a/lib/api/src/user/sshkey.rs b/lib/api/src/user/sshkey.rs
new file mode 100644
index 0000000..cd2e6d7
--- /dev/null
+++ b/lib/api/src/user/sshkey.rs
@@ -0,0 +1,99 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::sshkey::{CreateUserSshKey, UpdateUserSshKey, UserSshKey},
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/user/ssh-keys",
+    responses(
+        (status = 200, body = Vec<UserSshKey>)
+    ),
+    tag = "user"
+)]
+pub async fn list_ssh_keys(
+    service: web::Data<AppService>,
+    session: Session,
+) -> Result<HttpResponse, ApiError> {
+    let keys = service.user_ssh_keys(&session).await?;
+    ok_json(keys)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/user/ssh-keys",
+    request_body = CreateUserSshKey,
+    responses(
+        (status = 200, body = UserSshKey)
+    ),
+    tag = "user"
+)]
+pub async fn add_ssh_key(
+    service: web::Data<AppService>,
+    session: Session,
+    body: web::Json<CreateUserSshKey>,
+) -> Result<HttpResponse, ApiError> {
+    let key = service
+        .user_add_ssh_key(&session, body.into_inner())
+        .await?;
+    ok_json(key)
+}
+
+#[utoipa::path(
+    put,
+    path = "/api/v1/user/ssh-keys/{id}",
+    request_body = UpdateUserSshKey,
+    responses(
+        (status = 200, body = UserSshKey)
+    ),
+    params(
+        ("id" = i64, Path, description = "SSH key ID")
+    ),
+    tag = "user"
+)]
+pub async fn update_ssh_key(
+    service: web::Data<AppService>,
+    session: Session,
+    key_id: web::Path<i64>,
+    body: web::Json<UpdateUserSshKey>,
+) -> Result<HttpResponse, ApiError> {
+    let key = service
+        .user_update_ssh_key(&session, key_id.into_inner(), body.into_inner())
+        .await?;
+    ok_json(key)
+}
+
+#[utoipa::path(
+    delete,
+    path = "/api/v1/user/ssh-keys/{id}",
+    responses(
+        (status = 200)
+    ),
+    params(
+        ("id" = i64, Path, description = "SSH key ID")
+    ),
+    tag = "user"
+)]
+pub async fn revoke_ssh_key(
+    service: web::Data<AppService>,
+    session: Session,
+    key_id: web::Path<i64>,
+) -> Result<HttpResponse, ApiError> {
+    service
+        .user_revoke_ssh_key(&session, key_id.into_inner())
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/users/avatar.rs b/lib/api/src/users/avatar.rs
new file mode 100644
index 0000000..8643862
--- /dev/null
+++ b/lib/api/src/users/avatar.rs
@@ -0,0 +1,27 @@
+use actix_web::{HttpResponse, web};
+use service::AppService;
+
+use crate::error::ApiError;
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/avatar/{username}",
+    params(
+        ("username" = String, Path, description = "Username"),
+    ),
+    responses(
+        (status = 302, description = "Redirect to avatar image URL"),
+        (status = 404, description = "User or avatar not found"),
+    ),
+    tag = "users"
+)]
+pub async fn user_avatar(
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let username = path.into_inner();
+    let url = service.users_get_avatar_url(&username).await?;
+    Ok(HttpResponse::Found()
+        .insert_header(("Location", url))
+        .finish())
+}
diff --git a/lib/api/src/users/chpc.rs b/lib/api/src/users/chpc.rs
new file mode 100644
index 0000000..36f7a8e
--- /dev/null
+++ b/lib/api/src/users/chpc.rs
@@ -0,0 +1,30 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    user::chpc::{ContributionHeatmapQuery, ContributionHeatmapResponse},
+};
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/contribution-heatmap",
+    params(("username" = String, Path), ContributionHeatmapQuery),
+    responses((status = 200, body = ContributionHeatmapResponse)),
+    tag = "users"
+)]
+pub async fn user_chpc(
+    service: web::Data<AppService>,
+    username: web::Path<String>,
+    query: web::Query<ContributionHeatmapQuery>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_chpc_by_username(&username, query.into_inner())
+        .await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/users/mod.rs b/lib/api/src/users/mod.rs
new file mode 100644
index 0000000..2b1e3ac
--- /dev/null
+++ b/lib/api/src/users/mod.rs
@@ -0,0 +1,65 @@
+pub mod avatar;
+pub mod chpc;
+pub mod public;
+pub mod relation;
+pub mod summary;
+
+use actix_web::{web, web::ServiceConfig};
+
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::scope("/users")
+            .service(
+                web::resource("/avatar/{username}")
+                    .route(web::get().to(avatar::user_avatar)),
+            )
+            .service(
+                web::resource("/{username}/summary")
+                    .route(web::get().to(summary::user_summary)),
+            )
+            .service(
+                web::resource("/{username}/public")
+                    .route(web::get().to(public::user_public)),
+            )
+            .service(
+                web::resource("/{username}/contribution-heatmap")
+                    .route(web::get().to(chpc::user_chpc)),
+            )
+            .service(
+                web::resource("/{username}/follow")
+                    .route(web::post().to(relation::follow_user)),
+            )
+            .service(
+                web::resource("/{username}/unfollow")
+                    .route(web::post().to(relation::unfollow_user)),
+            )
+            .service(
+                web::resource("/{username}/block")
+                    .route(web::post().to(relation::block_user)),
+            )
+            .service(
+                web::resource("/{username}/unblock")
+                    .route(web::post().to(relation::unblock_user)),
+            )
+            .service(
+                web::resource("/{username}/relation")
+                    .route(web::get().to(relation::relation_status)),
+            )
+            .service(
+                web::resource("/{username}/followers")
+                    .route(web::get().to(relation::followers)),
+            )
+            .service(
+                web::resource("/{username}/following")
+                    .route(web::get().to(relation::following)),
+            )
+            .service(
+                web::resource("/blocked")
+                    .route(web::get().to(relation::blocked_list)),
+            )
+            .service(
+                web::resource("/{username}/relation-counts")
+                    .route(web::get().to(relation::relation_counts)),
+            ),
+    );
+}
diff --git a/lib/api/src/users/public.rs b/lib/api/src/users/public.rs
new file mode 100644
index 0000000..bf66086
--- /dev/null
+++ b/lib/api/src/users/public.rs
@@ -0,0 +1,24 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, users::public::PublicUserResponse};
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/public",
+    params(("username" = String, Path)),
+    responses((status = 200, body = PublicUserResponse)),
+    tag = "users"
+)]
+pub async fn user_public(
+    service: web::Data<AppService>,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.users_public_by_username(&username).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/users/relation.rs b/lib/api/src/users/relation.rs
new file mode 100644
index 0000000..82f8050
--- /dev/null
+++ b/lib/api/src/users/relation.rs
@@ -0,0 +1,178 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService, Pagination,
+    users::relation::{
+        UserRelationCard, UserRelationCounts, UserRelationStatus,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/users/{username}/follow",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserRelationStatus)),
+    tag = "users"
+)]
+pub async fn follow_user(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_follow_by_username(&session, &username)
+        .await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/users/{username}/unfollow",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserRelationStatus)),
+    tag = "users"
+)]
+pub async fn unfollow_user(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_unfollow_by_username(&session, &username)
+        .await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/users/{username}/block",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserRelationStatus)),
+    tag = "users"
+)]
+pub async fn block_user(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.users_block_by_username(&session, &username).await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/users/{username}/unblock",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserRelationStatus)),
+    tag = "users"
+)]
+pub async fn unblock_user(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_unblock_by_username(&session, &username)
+        .await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/relation",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserRelationStatus)),
+    tag = "users"
+)]
+pub async fn relation_status(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_relation_status_by_username(&session, &username)
+        .await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/followers",
+    params(("username" = String, Path), Pagination),
+    responses((status = 200, body = Vec<UserRelationCard>)),
+    tag = "users"
+)]
+pub async fn followers(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_followers_by_username(
+            Some(&session),
+            &username,
+            pagination.into_inner(),
+        )
+        .await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/following",
+    params(("username" = String, Path), Pagination),
+    responses((status = 200, body = Vec<UserRelationCard>)),
+    tag = "users"
+)]
+pub async fn following(
+    service: web::Data<AppService>,
+    session: Session,
+    username: web::Path<String>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service
+        .users_following_by_username(
+            Some(&session),
+            &username,
+            pagination.into_inner(),
+        )
+        .await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/blocked",
+    responses((status = 200, body = Vec<UserRelationCard>)),
+    tag = "users"
+)]
+pub async fn blocked_list(
+    service: web::Data<AppService>,
+    session: Session,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.users_blocked(&session).await?;
+    ok_json(result)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/relation-counts",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserRelationCounts)),
+    tag = "users"
+)]
+pub async fn relation_counts(
+    service: web::Data<AppService>,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.users_relation_counts_by_username(&username).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/users/summary.rs b/lib/api/src/users/summary.rs
new file mode 100644
index 0000000..855b31f
--- /dev/null
+++ b/lib/api/src/users/summary.rs
@@ -0,0 +1,24 @@
+use actix_web::{HttpResponse, web};
+use serde::Serialize;
+use service::{AppService, users::summary::UserSummaryResponse};
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/users/{username}/summary",
+    params(("username" = String, Path)),
+    responses((status = 200, body = UserSummaryResponse)),
+    tag = "users"
+)]
+pub async fn user_summary(
+    service: web::Data<AppService>,
+    username: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let result = service.users_summary_by_username(&username).await?;
+    ok_json(result)
+}
diff --git a/lib/api/src/workspace/group.rs b/lib/api/src/workspace/group.rs
new file mode 100644
index 0000000..f7a0d54
--- /dev/null
+++ b/lib/api/src/workspace/group.rs
@@ -0,0 +1,222 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    workspace::{
+        group::{CreateWorkspaceGroup, UpdateWorkspaceGroup},
+        types::{WorkspaceGroupResponse, WorkspaceMemberResponse},
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct GroupPath {
+    pub wk: String,
+    pub group_name: String,
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct GroupMemberPath {
+    pub wk: String,
+    pub group_name: String,
+    pub username: String,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/groups",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 200, body = Vec<WorkspaceGroupResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Workspace not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_groups(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service.workspace_groups(&session, &wk).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/groups",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = CreateWorkspaceGroup,
+    responses(
+        (status = 200, body = WorkspaceGroupResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn create_group(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<CreateWorkspaceGroup>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_create_group(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/groups/{group_name}",
+    params(GroupPath),
+    request_body = UpdateWorkspaceGroup,
+    responses(
+        (status = 200, body = WorkspaceGroupResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Group not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_group(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<GroupPath>,
+    params: web::Json<UpdateWorkspaceGroup>,
+) -> Result<HttpResponse, ApiError> {
+    let GroupPath { wk, group_name } = path.into_inner();
+    let data = service
+        .workspace_update_group(
+            &session,
+            &wk,
+            &group_name,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/groups/{group_name}",
+    params(GroupPath),
+    responses(
+        (status = 200, description = "Group deleted"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Group not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn delete_group(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<GroupPath>,
+) -> Result<HttpResponse, ApiError> {
+    let GroupPath { wk, group_name } = path.into_inner();
+    service
+        .workspace_delete_group(&session, &wk, &group_name)
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/groups/{group_name}/members/{username}",
+    params(GroupMemberPath),
+    responses(
+        (status = 200, description = "Member added to group"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn add_group_member(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<GroupMemberPath>,
+) -> Result<HttpResponse, ApiError> {
+    let GroupMemberPath {
+        wk,
+        group_name,
+        username,
+    } = path.into_inner();
+    service
+        .workspace_add_group_member(&session, &wk, &group_name, &username)
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/groups/{group_name}/members/{username}",
+    params(GroupMemberPath),
+    responses(
+        (status = 200, description = "Member removed from group"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn remove_group_member(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<GroupMemberPath>,
+) -> Result<HttpResponse, ApiError> {
+    let GroupMemberPath {
+        wk,
+        group_name,
+        username,
+    } = path.into_inner();
+    service
+        .workspace_remove_group_member(&session, &wk, &group_name, &username)
+        .await?;
+    ok()
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/groups/{group_name}/members",
+    params(GroupPath),
+    responses(
+        (status = 200, body = Vec<WorkspaceMemberResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Group not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_group_members(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<GroupPath>,
+) -> Result<HttpResponse, ApiError> {
+    let GroupPath { wk, group_name } = path.into_inner();
+    let data = service
+        .workspace_group_members(&session, &wk, &group_name)
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/workspace/join.rs b/lib/api/src/workspace/join.rs
new file mode 100644
index 0000000..7d87635
--- /dev/null
+++ b/lib/api/src/workspace/join.rs
@@ -0,0 +1,202 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService,
+    workspace::join::{
+        ApproveWorkspaceJoinApply, CreateWorkspaceJoinApply,
+        ListWorkspaceJoinApply, UpdateWorkspaceJoinStrategy,
+        WorkspaceJoinApplyResponse, WorkspaceJoinApprovalResponse,
+        WorkspaceJoinStrategyResponse,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct ApplyApprovePath {
+    pub wk: String,
+    pub username: String,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/join-strategy",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 200, body = WorkspaceJoinStrategyResponse),
+        (status = 404, description = "Workspace not found"),
+    )
+)]
+pub async fn join_strategy(
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service.workspace_join_strategy(&wk).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/join-strategy",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = UpdateWorkspaceJoinStrategy,
+    responses(
+        (status = 200, body = WorkspaceJoinStrategyResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Workspace not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_join_strategy(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<UpdateWorkspaceJoinStrategy>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_update_join_strategy(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/join/apply",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = CreateWorkspaceJoinApply,
+    responses(
+        (status = 200, body = WorkspaceJoinApplyResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 409, description = "Already a member or pending application"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn apply_join(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<CreateWorkspaceJoinApply>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_apply_join(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/join/my-applies",
+    responses(
+        (status = 200, body = Vec<WorkspaceJoinApplyResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn my_join_applies(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let data = service.workspace_my_join_applies(&session).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/join/cancel",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 200, body = WorkspaceJoinApplyResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Application not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn cancel_join(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service.workspace_cancel_join_apply(&session, &wk).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/join/applies",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        ListWorkspaceJoinApply,
+    ),
+    responses(
+        (status = 200, body = Vec<WorkspaceJoinApplyResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_join_applies(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    query: web::Query<ListWorkspaceJoinApply>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_join_applies(&session, &wk, query.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/join/applies/{username}/approve",
+    params(ApplyApprovePath),
+    request_body = ApproveWorkspaceJoinApply,
+    responses(
+        (status = 200, body = WorkspaceJoinApprovalResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Application not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn approve_join(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<ApplyApprovePath>,
+    params: web::Json<ApproveWorkspaceJoinApply>,
+) -> Result<HttpResponse, ApiError> {
+    let ApplyApprovePath { wk, username } = path.into_inner();
+    let data = service
+        .workspace_approve_join_apply(
+            &session,
+            &wk,
+            &username,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
diff --git a/lib/api/src/workspace/member.rs b/lib/api/src/workspace/member.rs
new file mode 100644
index 0000000..2845607
--- /dev/null
+++ b/lib/api/src/workspace/member.rs
@@ -0,0 +1,137 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+use service::{
+    AppService, Pagination,
+    workspace::{
+        member::{AddWorkspaceMember, UpdateWorkspaceMember},
+        types::WorkspaceMemberResponse,
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+
+fn ok() -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().finish())
+}
+
+#[derive(Deserialize, utoipa::IntoParams)]
+pub struct MemberPath {
+    pub wk: String,
+    pub username: String,
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/members",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+        Pagination,
+    ),
+    responses(
+        (status = 200, body = Vec<WorkspaceMemberResponse>),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Workspace not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn list_members(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    pagination: web::Query<Pagination>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_members(&session, &wk, pagination.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/members",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = AddWorkspaceMember,
+    responses(
+        (status = 200, body = WorkspaceMemberResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn add_member(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<AddWorkspaceMember>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_add_member(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}/members/{username}",
+    params(MemberPath),
+    request_body = UpdateWorkspaceMember,
+    responses(
+        (status = 200, body = WorkspaceMemberResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_member(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<MemberPath>,
+    params: web::Json<UpdateWorkspaceMember>,
+) -> Result<HttpResponse, ApiError> {
+    let MemberPath { wk, username } = path.into_inner();
+    let data = service
+        .workspace_update_member(
+            &session,
+            &wk,
+            &username,
+            params.into_inner(),
+        )
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    delete,
+    path = "/api/v1/workspace/{wk}/members/{username}",
+    params(MemberPath),
+    responses(
+        (status = 200, description = "Member removed"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn remove_member(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<MemberPath>,
+) -> Result<HttpResponse, ApiError> {
+    let MemberPath { wk, username } = path.into_inner();
+    service
+        .workspace_remove_member(&session, &wk, &username)
+        .await?;
+    ok()
+}
diff --git a/lib/api/src/workspace/mod.rs b/lib/api/src/workspace/mod.rs
new file mode 100644
index 0000000..0c442eb
--- /dev/null
+++ b/lib/api/src/workspace/mod.rs
@@ -0,0 +1,82 @@
+pub mod group;
+pub mod join;
+pub mod member;
+pub mod workspace;
+
+use actix_web::{web, web::ServiceConfig};
+pub fn configure(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("")
+            .route(web::post().to(workspace::create_workspace)),
+    );
+    cfg.service(
+        web::resource("/my")
+            .route(web::get().to(workspace::my_workspaces)),
+    );
+    cfg.service(
+        web::resource("/join/my-applies")
+            .route(web::get().to(join::my_join_applies)),
+    );
+}
+pub fn configure_wk(cfg: &mut ServiceConfig) {
+    cfg.service(
+        web::resource("")
+            .route(web::get().to(workspace::get_workspace))
+            .route(web::put().to(workspace::update_workspace)),
+    );
+    cfg.service(
+        web::resource("/avatar")
+            .route(web::get().to(workspace::get_avatar))
+            .route(web::post().to(workspace::upload_avatar)),
+    );
+    cfg.service(
+        web::resource("/members")
+            .route(web::get().to(member::list_members))
+            .route(web::post().to(member::add_member)),
+    );
+    cfg.service(
+        web::resource("/members/{username}")
+            .route(web::put().to(member::update_member))
+            .route(web::delete().to(member::remove_member)),
+    );
+    cfg.service(
+        web::resource("/groups")
+            .route(web::get().to(group::list_groups))
+            .route(web::post().to(group::create_group)),
+    );
+    cfg.service(
+        web::resource("/groups/{group_name}")
+            .route(web::put().to(group::update_group))
+            .route(web::delete().to(group::delete_group)),
+    );
+    cfg.service(
+        web::resource("/groups/{group_name}/members/{username}")
+            .route(web::post().to(group::add_group_member))
+            .route(web::delete().to(group::remove_group_member)),
+    );
+    cfg.service(
+        web::resource("/groups/{group_name}/members")
+            .route(web::get().to(group::list_group_members)),
+    );
+    cfg.service(
+        web::resource("/join-strategy")
+            .route(web::get().to(join::join_strategy))
+            .route(web::put().to(join::update_join_strategy)),
+    );
+    cfg.service(
+        web::resource("/join/apply")
+            .route(web::post().to(join::apply_join)),
+    );
+    cfg.service(
+        web::resource("/join/cancel")
+            .route(web::post().to(join::cancel_join)),
+    );
+    cfg.service(
+        web::resource("/join/applies")
+            .route(web::get().to(join::list_join_applies)),
+    );
+    cfg.service(
+        web::resource("/join/applies/{username}/approve")
+            .route(web::post().to(join::approve_join)),
+    );
+}
diff --git a/lib/api/src/workspace/workspace.rs b/lib/api/src/workspace/workspace.rs
new file mode 100644
index 0000000..fcf443d
--- /dev/null
+++ b/lib/api/src/workspace/workspace.rs
@@ -0,0 +1,169 @@
+use actix_web::{HttpRequest, HttpResponse, web};
+use serde::Serialize;
+use service::{
+    AppService,
+    workspace::{
+        types::WorkspaceResponse,
+        workspace::{AvatarUploadResponse, CreateWorkspace, UpdateWorkspace},
+    },
+};
+use session::Session;
+
+use crate::error::ApiError;
+
+fn ok_json<T: Serialize>(data: T) -> Result<HttpResponse, ApiError> {
+    Ok(HttpResponse::Ok().json(data))
+}
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace",
+    request_body = CreateWorkspace,
+    responses(
+        (status = 200, body = WorkspaceResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 409, description = "Workspace name already exists"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn create_workspace(
+    session: Session,
+    service: web::Data<AppService>,
+    params: web::Json<CreateWorkspace>,
+) -> Result<HttpResponse, ApiError> {
+    let data = service
+        .workspace_create(&session, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/my",
+    responses(
+        (status = 200, body = Vec<WorkspaceResponse>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn my_workspaces(
+    session: Session,
+    service: web::Data<AppService>,
+) -> Result<HttpResponse, ApiError> {
+    let data = service.workspace_my(&session).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 200, body = WorkspaceResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 404, description = "Workspace not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn get_workspace(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service.workspace_get(&session, &wk).await?;
+    ok_json(data)
+}
+#[utoipa::path(
+    put,
+    path = "/api/v1/workspace/{wk}",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body = UpdateWorkspace,
+    responses(
+        (status = 200, body = WorkspaceResponse),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Permission denied"),
+        (status = 404, description = "Workspace not found"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn update_workspace(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    params: web::Json<UpdateWorkspace>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let data = service
+        .workspace_update(&session, &wk, params.into_inner())
+        .await?;
+    ok_json(data)
+}
+
+#[utoipa::path(
+    get,
+    path = "/api/v1/workspace/{wk}/avatar",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    responses(
+        (status = 302, description = "Redirect to avatar image URL"),
+        (status = 404, description = "Workspace or avatar not found"),
+    ),
+    tag = "workspace"
+)]
+pub async fn get_avatar(
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let url = service.workspace_get_avatar_url(&wk).await?;
+    Ok(HttpResponse::Found()
+        .insert_header(("Location", url))
+        .finish())
+}
+
+#[utoipa::path(
+    post,
+    path = "/api/v1/workspace/{wk}/avatar",
+    params(
+        ("wk" = String, Path, description = "Workspace name"),
+    ),
+    request_body(content = Vec<u8>, content_type = "image/*"),
+    responses(
+        (status = 200, body = AvatarUploadResponse),
+        (status = 400, description = "Invalid file type or size"),
+        (status = 403, description = "Permission denied"),
+    ),
+    security(
+        ("session" = [])
+    )
+)]
+pub async fn upload_avatar(
+    session: Session,
+    service: web::Data<AppService>,
+    path: web::Path<String>,
+    body: web::Bytes,
+    req: HttpRequest,
+) -> Result<HttpResponse, ApiError> {
+    let wk = path.into_inner();
+    let content_type = req
+        .headers()
+        .get("content-type")
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("application/octet-stream");
+
+    let response = service
+        .workspace_upload_avatar(&session, &wk, body.to_vec(), content_type)
+        .await?;
+    ok_json(response)
+}
diff --git a/lib/cache/Cargo.toml b/lib/cache/Cargo.toml
new file mode 100644
index 0000000..c94c283
--- /dev/null
+++ b/lib/cache/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "cache"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "cache"
+[dependencies]
+redis = { workspace = true, features = ["cluster-async", "aio","cache-aio","tokio-comp","r2d2"] }
+tokio = { workspace = true, features = ["full"] }
+moka = { workspace = true, features = ["future"] }
+serde_json = { workspace = true }
+serde = { workspace = true }
+config = { workspace = true }
+[lints]
+workspace = true
diff --git a/lib/cache/cluster.rs b/lib/cache/cluster.rs
new file mode 100644
index 0000000..4bde828
--- /dev/null
+++ b/lib/cache/cluster.rs
@@ -0,0 +1,205 @@
+use std::{sync::Arc, time::Duration};
+
+use redis::{
+    AsyncCommands, cluster::ClusterClient, cluster_async::ClusterConnection,
+};
+use serde::{Serialize, de::DeserializeOwned};
+use tokio::time::timeout;
+
+use crate::{CacheError, CacheResult};
+
+const DEFAULT_COMMAND_TIMEOUT: Duration = Duration::from_secs(3);
+
+#[derive(Clone, Debug)]
+pub struct ClusterCacheConfig {
+    pub urls: Vec<String>,
+    pub key_prefix: Option<String>,
+    pub command_timeout: Duration,
+}
+
+impl ClusterCacheConfig {
+    pub fn new(urls: Vec<String>) -> Self {
+        Self {
+            urls,
+            key_prefix: None,
+            command_timeout: DEFAULT_COMMAND_TIMEOUT,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct ClusterCache {
+    connection: ClusterConnection,
+    key_prefix: Option<Arc<str>>,
+    command_timeout: Duration,
+}
+
+impl ClusterCache {
+    pub async fn connect(config: ClusterCacheConfig) -> CacheResult<Self> {
+        if config.urls.is_empty() {
+            return Err(CacheError::Config(
+                "redis cluster urls are empty".to_string(),
+            ));
+        }
+
+        let client =
+            ClusterClient::new(config.urls).map_err(CacheError::Redis)?;
+        let connection =
+            timeout(config.command_timeout, client.get_async_connection())
+                .await
+                .map_err(|_| CacheError::Timeout("connect redis cluster"))?
+                .map_err(CacheError::Redis)?;
+
+        Ok(Self {
+            connection,
+            key_prefix: config.key_prefix.map(Arc::from),
+            command_timeout: config.command_timeout,
+        })
+    }
+
+    pub async fn get<T>(&self, key: &str) -> CacheResult<Option<T>>
+    where
+        T: DeserializeOwned,
+    {
+        let key = self.key(key);
+        let mut connection = self.connection.clone();
+        let value: Option<Vec<u8>> = self
+            .run(redis::cmd("GET").arg(&key).query_async(&mut connection))
+            .await?;
+
+        match value {
+            Some(value) => serde_json::from_slice(&value)
+                .map(Some)
+                .map_err(CacheError::Serialize),
+            None => Ok(None),
+        }
+    }
+
+    pub async fn get_json(
+        &self,
+        key: &str,
+    ) -> CacheResult<Option<serde_json::Value>> {
+        self.get(key).await
+    }
+
+    pub async fn set<T>(
+        &self,
+        key: &str,
+        value: &T,
+        ttl: Option<Duration>,
+    ) -> CacheResult<()>
+    where
+        T: Serialize + ?Sized,
+    {
+        let key = self.key(key);
+        let value = serde_json::to_vec(value).map_err(CacheError::Serialize)?;
+        let mut connection = self.connection.clone();
+
+        if let Some(ttl) = ttl {
+            let seconds = ttl.as_secs().max(1);
+            self.run::<(), _>(connection.set_ex(key, value, seconds))
+                .await
+        } else {
+            self.run::<(), _>(connection.set(key, value)).await
+        }
+    }
+
+    pub async fn remove(&self, key: &str) -> CacheResult<bool> {
+        let key = self.key(key);
+        let mut connection = self.connection.clone();
+        let removed: u64 = self.run(connection.del(key)).await?;
+        Ok(removed > 0)
+    }
+
+    pub async fn exists(&self, key: &str) -> CacheResult<bool> {
+        let key = self.key(key);
+        let mut connection = self.connection.clone();
+        self.run(connection.exists(key)).await
+    }
+
+    pub async fn set_nx_with_ttl<T>(
+        &self,
+        key: &str,
+        value: &T,
+        ttl: Duration,
+    ) -> CacheResult<bool>
+    where
+        T: Serialize,
+    {
+        let key = self.key(key);
+        let value = serde_json::to_vec(value).map_err(CacheError::Serialize)?;
+        let mut connection = self.connection.clone();
+        let result: Option<String> = self
+            .run(
+                redis::cmd("SET")
+                    .arg(&key)
+                    .arg(&value)
+                    .arg("NX")
+                    .arg("EX")
+                    .arg(ttl.as_secs().max(1))
+                    .query_async(&mut connection),
+            )
+            .await?;
+        Ok(result.is_some())
+    }
+
+    pub async fn expire(&self, key: &str, ttl: Duration) -> CacheResult<bool> {
+        let key = self.key(key);
+        let mut connection = self.connection.clone();
+        self.run(connection.expire(key, ttl.as_secs() as i64)).await
+    }
+
+    pub async fn delete_pattern(&self, pattern: &str) -> CacheResult<u64> {
+        let pattern = self.key(pattern);
+        let mut connection = self.connection.clone();
+        let keys: Vec<String> = self
+            .run(
+                redis::cmd("KEYS")
+                    .arg(&pattern)
+                    .query_async(&mut connection),
+            )
+            .await?;
+
+        if keys.is_empty() {
+            return Ok(0);
+        }
+
+        let mut connection = self.connection.clone();
+        self.run(connection.del(keys)).await
+    }
+
+    pub async fn ping(&self) -> CacheResult<()> {
+        let mut connection = self.connection.clone();
+        let pong: String = self
+            .run(redis::cmd("PING").query_async(&mut connection))
+            .await?;
+        if pong == "PONG" {
+            Ok(())
+        } else {
+            Err(CacheError::Protocol(format!(
+                "unexpected redis PING response: {pong}"
+            )))
+        }
+    }
+
+    pub fn conn(&self) -> ClusterConnection {
+        self.connection.clone()
+    }
+
+    fn key(&self, key: &str) -> String {
+        match &self.key_prefix {
+            Some(prefix) => format!("{prefix}:{key}"),
+            None => key.to_string(),
+        }
+    }
+
+    async fn run<T, F>(&self, future: F) -> CacheResult<T>
+    where
+        F: std::future::Future<Output = redis::RedisResult<T>>,
+    {
+        timeout(self.command_timeout, future)
+            .await
+            .map_err(|_| CacheError::Timeout("redis command"))?
+            .map_err(CacheError::Redis)
+    }
+}
diff --git a/lib/cache/error.rs b/lib/cache/error.rs
new file mode 100644
index 0000000..54afe92
--- /dev/null
+++ b/lib/cache/error.rs
@@ -0,0 +1,44 @@
+use std::fmt;
+
+#[derive(Debug)]
+pub enum CacheError {
+    Config(String),
+    Protocol(String),
+    Redis(redis::RedisError),
+    Serialize(serde_json::Error),
+    Timeout(&'static str),
+}
+
+impl fmt::Display for CacheError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Config(message) => {
+                write!(formatter, "cache config error: {message}")
+            }
+            Self::Protocol(message) => {
+                write!(formatter, "cache protocol error: {message}")
+            }
+            Self::Redis(error) => {
+                write!(formatter, "redis cache error: {error}")
+            }
+            Self::Serialize(error) => {
+                write!(formatter, "cache serialization error: {error}")
+            }
+            Self::Timeout(operation) => {
+                write!(formatter, "cache operation timed out: {operation}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for CacheError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Redis(error) => Some(error),
+            Self::Serialize(error) => Some(error),
+            Self::Config(_) | Self::Protocol(_) | Self::Timeout(_) => None,
+        }
+    }
+}
+
+pub type CacheResult<T> = Result<T, CacheError>;
diff --git a/lib/cache/lib.rs b/lib/cache/lib.rs
new file mode 100644
index 0000000..7eb326d
--- /dev/null
+++ b/lib/cache/lib.rs
@@ -0,0 +1,209 @@
+pub mod cluster;
+pub mod error;
+pub mod local;
+
+use std::time::Duration;
+
+pub use crate::{
+    cluster::{ClusterCache, ClusterCacheConfig},
+    error::{CacheError, CacheResult},
+    local::{LocalCacheConfig, MokaCache},
+};
+
+#[derive(Clone, Debug)]
+pub struct AppCacheConfig {
+    pub local: LocalCacheConfig,
+    pub cluster: Option<ClusterCacheConfig>,
+    pub default_ttl: Option<Duration>,
+    pub cluster_write_through: bool,
+}
+
+impl Default for AppCacheConfig {
+    fn default() -> Self {
+        Self {
+            local: LocalCacheConfig::default(),
+            cluster: None,
+            default_ttl: Some(Duration::from_secs(300)),
+            cluster_write_through: true,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct AppCache {
+    pub local: MokaCache,
+    pub cluster: Option<ClusterCache>,
+    default_ttl: Option<Duration>,
+    cluster_write_through: bool,
+}
+
+impl AppCache {
+    pub async fn init(config: AppCacheConfig) -> CacheResult<Self> {
+        let local = MokaCache::with_config(config.local);
+        let cluster = match config.cluster {
+            Some(cluster) => Some(match ClusterCache::connect(cluster).await {
+                Ok(cluster) => cluster,
+                Err(e) => {
+                    println!("cache:init:error with: {}", e);
+                    return Err(e);
+                }
+            }),
+            None => None,
+        };
+
+        Ok(Self {
+            local,
+            cluster,
+            default_ttl: config.default_ttl,
+            cluster_write_through: config.cluster_write_through,
+        })
+    }
+
+    pub fn local_only(local: MokaCache) -> Self {
+        Self {
+            local,
+            cluster: None,
+            default_ttl: None,
+            cluster_write_through: false,
+        }
+    }
+
+    pub async fn get<T>(&self, key: &str) -> CacheResult<Option<T>>
+    where
+        T: serde::Serialize + serde::de::DeserializeOwned,
+    {
+        if let Some(value) = self.local.get(key).await? {
+            return Ok(Some(value));
+        }
+
+        let Some(cluster) = &self.cluster else {
+            return Ok(None);
+        };
+
+        let value = cluster.get::<T>(key).await?;
+        if let Some(value) = &value {
+            self.local.set(key, value).await?;
+        }
+        Ok(value)
+    }
+
+    pub async fn set<T>(&self, key: &str, value: &T) -> CacheResult<()>
+    where
+        T: serde::Serialize + ?Sized,
+    {
+        self.local.set(key, value).await?;
+        if self.cluster_write_through
+            && let Some(cluster) = &self.cluster
+        {
+            cluster.set(key, value, self.default_ttl).await?;
+        }
+        Ok(())
+    }
+
+    pub async fn remove(&self, key: &str) -> CacheResult<()> {
+        self.local.remove(key).await;
+        if let Some(cluster) = &self.cluster {
+            cluster.remove(key).await?;
+        }
+        Ok(())
+    }
+    pub async fn delete_pattern(&self, pattern: &str) -> CacheResult<u64> {
+        let pattern = pattern.to_string();
+        let local_pattern = pattern.clone();
+        self.local.invalidate_entries_if(move |key| {
+            simple_glob_match(&local_pattern, key)
+        });
+
+        let mut removed = 0u64;
+        if let Some(cluster) = &self.cluster {
+            removed = cluster.delete_pattern(&pattern).await?;
+        }
+        Ok(removed)
+    }
+
+    pub async fn ping_cluster(&self) -> CacheResult<()> {
+        if let Some(cluster) = &self.cluster {
+            cluster.ping().await?;
+        }
+        Ok(())
+    }
+
+    pub fn conn(&self) -> Option<redis::cluster_async::ClusterConnection> {
+        self.cluster.as_ref().map(|c| c.conn())
+    }
+}
+
+impl TryFrom<&config::AppConfig> for AppCacheConfig {
+    type Error = CacheError;
+
+    fn try_from(config: &config::AppConfig) -> Result<Self, Self::Error> {
+        let local = LocalCacheConfig {
+            max_capacity: config
+                .cache_local_max_capacity()
+                .map_err(|error| CacheError::Config(error.to_string()))?,
+            time_to_live: config
+                .cache_local_ttl()
+                .map_err(|error| CacheError::Config(error.to_string()))?,
+            time_to_idle: config
+                .cache_local_tti()
+                .map_err(|error| CacheError::Config(error.to_string()))?,
+        };
+
+        let cluster = if config
+            .cache_cluster_enabled()
+            .map_err(|error| CacheError::Config(error.to_string()))?
+        {
+            Some(ClusterCacheConfig {
+                urls: config
+                    .redis_urls()
+                    .map_err(|error| CacheError::Config(error.to_string()))?,
+                key_prefix: config.cache_cluster_key_prefix(),
+                command_timeout: config
+                    .cache_cluster_command_timeout()
+                    .map_err(|error| CacheError::Config(error.to_string()))?,
+            })
+        } else {
+            None
+        };
+
+        Ok(Self {
+            local,
+            cluster,
+            default_ttl: config
+                .cache_default_ttl()
+                .map_err(|error| CacheError::Config(error.to_string()))?,
+            cluster_write_through: config
+                .cache_cluster_write_through()
+                .map_err(|error| CacheError::Config(error.to_string()))?,
+        })
+    }
+}
+fn simple_glob_match(pattern: &str, key: &str) -> bool {
+    let p = pattern.as_bytes();
+    let k = key.as_bytes();
+    let (mut pi, mut ki) = (0usize, 0usize);
+
+    let mut backtrack_p: Option<usize> = None;
+    let mut backtrack_k: usize = 0;
+
+    loop {
+        if pi < p.len() && ki < k.len() && (p[pi] == b'?' || p[pi] == k[ki]) {
+            pi += 1;
+            ki += 1;
+        } else if pi < p.len() && p[pi] == b'*' {
+            backtrack_p = Some(pi);
+            backtrack_k = ki;
+            pi += 1;
+        } else if let Some(saved_pi) = backtrack_p {
+            backtrack_k += 1;
+            ki = backtrack_k;
+            pi = saved_pi + 1;
+        } else {
+            return pi == p.len() && ki == k.len();
+        }
+
+        if pi == p.len() && ki == k.len() {
+            return true;
+        }
+    }
+}
diff --git a/lib/cache/local.rs b/lib/cache/local.rs
new file mode 100644
index 0000000..dd3d6ad
--- /dev/null
+++ b/lib/cache/local.rs
@@ -0,0 +1,143 @@
+use std::{sync::Arc, time::Duration};
+
+use moka::future::{Cache, CacheBuilder};
+use serde::{Serialize, de::DeserializeOwned};
+
+use crate::{CacheError, CacheResult};
+
+const DEFAULT_LOCAL_MAX_CAPACITY: u64 = 10_000;
+
+#[derive(Clone, Debug)]
+pub struct LocalCacheConfig {
+    pub max_capacity: u64,
+    pub time_to_live: Option<Duration>,
+    pub time_to_idle: Option<Duration>,
+}
+
+impl Default for LocalCacheConfig {
+    fn default() -> Self {
+        Self {
+            max_capacity: DEFAULT_LOCAL_MAX_CAPACITY,
+            time_to_live: Some(Duration::from_secs(300)),
+            time_to_idle: None,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct MokaCache {
+    pub(crate) inner: Cache<Arc<str>, Arc<[u8]>>,
+}
+
+impl MokaCache {
+    pub fn init() -> Self {
+        Self::with_config(LocalCacheConfig::default())
+    }
+
+    pub fn with_config(config: LocalCacheConfig) -> Self {
+        let mut builder = CacheBuilder::new(config.max_capacity);
+        if let Some(time_to_live) = config.time_to_live {
+            builder = builder.time_to_live(time_to_live);
+        }
+        if let Some(time_to_idle) = config.time_to_idle {
+            builder = builder.time_to_idle(time_to_idle);
+        }
+
+        Self {
+            inner: builder.build(),
+        }
+    }
+
+    pub async fn get<T>(&self, key: &str) -> CacheResult<Option<T>>
+    where
+        T: DeserializeOwned,
+    {
+        match self.inner.get(key).await {
+            Some(value) => serde_json::from_slice(value.as_ref())
+                .map(Some)
+                .map_err(CacheError::Serialize),
+            None => Ok(None),
+        }
+    }
+
+    pub async fn get_json(
+        &self,
+        key: &str,
+    ) -> CacheResult<Option<serde_json::Value>> {
+        self.get(key).await
+    }
+
+    pub async fn set<T>(&self, key: &str, value: &T) -> CacheResult<()>
+    where
+        T: Serialize + ?Sized,
+    {
+        let value = serde_json::to_vec(value).map_err(CacheError::Serialize)?;
+        self.inner
+            .insert(Arc::<str>::from(key), Arc::<[u8]>::from(value))
+            .await;
+        Ok(())
+    }
+
+    pub async fn remove(&self, key: &str) {
+        self.inner.remove(key).await;
+    }
+
+    pub async fn contains_key(&self, key: &str) -> bool {
+        self.inner.contains_key(key)
+    }
+
+    pub async fn invalidate_all(&self) {
+        self.inner.invalidate_all();
+    }
+
+    pub fn invalidate_entries_if<F>(&self, predicate: F)
+    where
+        F: Fn(&str) -> bool + Send + Sync + 'static,
+    {
+        let _ = self
+            .inner
+            .invalidate_entries_if(move |key, _| predicate(key));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::Duration;
+
+    use serde::{Deserialize, Serialize};
+
+    use super::{LocalCacheConfig, MokaCache};
+
+    #[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
+    struct User {
+        id: u64,
+        name: String,
+    }
+
+    #[tokio::test]
+    async fn stores_and_reads_typed_values() {
+        let cache = MokaCache::init();
+        let user = User {
+            id: 7,
+            name: "alice".to_string(),
+        };
+
+        cache.set("user:7", &user).await.unwrap();
+
+        assert_eq!(cache.get::<User>("user:7").await.unwrap(), Some(user));
+    }
+
+    #[tokio::test]
+    async fn expires_values_by_ttl() {
+        let cache = MokaCache::with_config(LocalCacheConfig {
+            max_capacity: 16,
+            time_to_live: Some(Duration::from_millis(25)),
+            time_to_idle: None,
+        });
+
+        cache.set("short", &"value").await.unwrap();
+        tokio::time::sleep(Duration::from_millis(60)).await;
+
+        assert_eq!(cache.get::<String>("short").await.unwrap(), None);
+    }
+}
diff --git a/lib/channel/Cargo.toml b/lib/channel/Cargo.toml
new file mode 100644
index 0000000..f52ccec
--- /dev/null
+++ b/lib/channel/Cargo.toml
@@ -0,0 +1,39 @@
+[package]
+name = "channel"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+[lib]
+path = "lib.rs"
+name = "channel"
+[dependencies]
+cache = { workspace = true }
+chrono = { workspace = true, features = ["serde"] }
+db = { workspace = true }
+dashmap = { workspace = true }
+futures = { workspace = true }
+hmac = "0.13"
+sha2 = { workspace = true }
+base64 = { workspace = true }
+model = { workspace = true }
+redis = { workspace = true, features = ["cluster"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+socketio = { workspace = true }
+sqlx = { workspace = true }
+storage = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["sync", "time"] }
+tokio-util = { workspace = true }
+tracing = { workspace = true }
+uuid = { workspace = true, features = ["serde", "v7"] }
+[lints]
+workspace = true
diff --git a/lib/channel/ack.rs b/lib/channel/ack.rs
new file mode 100644
index 0000000..f60e6c1
--- /dev/null
+++ b/lib/channel/ack.rs
@@ -0,0 +1,162 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::ChannelResult;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageAck {
+    pub message_id: Uuid,
+    pub room_id: Uuid,
+    pub seq: i64,
+    pub status: AckStatus,
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum AckStatus {
+    Pending,
+    Received,
+    Persisted,
+    Delivered,
+    Failed,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AckRequest {
+    pub message_id: Uuid,
+    pub room_id: Uuid,
+    pub client_timestamp: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AckResponse {
+    pub message_id: Uuid,
+    pub status: AckStatus,
+    pub seq: Option<i64>,
+    pub server_timestamp: chrono::DateTime<chrono::Utc>,
+    pub error: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct AckTracker {
+    cache: cache::AppCache,
+    timeout: std::time::Duration,
+}
+
+impl AckTracker {
+    pub fn new(cache: cache::AppCache) -> Self {
+        Self::with_config(cache, std::time::Duration::from_secs(30))
+    }
+
+    pub fn with_config(
+        cache: cache::AppCache,
+        timeout: std::time::Duration,
+    ) -> Self {
+        Self { cache, timeout }
+    }
+    async fn set_with_ttl<T>(&self, key: &str, value: &T) -> ChannelResult<()>
+    where
+        T: serde::Serialize,
+    {
+        self.cache.set(key, value).await?;
+        if let Some(cluster) = &self.cache.cluster {
+            if let Err(e) = cluster.expire(key, self.timeout).await {
+                tracing::warn!(error = %e, "ack TTL override failed, using default cache TTL");
+            }
+        }
+        Ok(())
+    }
+
+    pub async fn track_pending(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+        user_id: Uuid,
+    ) -> ChannelResult<()> {
+        let key = format!("ack:pending:{}:{}", room_id, message_id);
+        let ack = MessageAck {
+            message_id,
+            room_id,
+            seq: 0,
+            status: AckStatus::Pending,
+            timestamp: chrono::Utc::now(),
+        };
+        let owner_key = format!("ack:owner:{}:{}", room_id, message_id);
+        self.set_with_ttl(&key, &ack).await?;
+        self.set_with_ttl(&owner_key, &user_id.to_string()).await?;
+        Ok(())
+    }
+
+    pub async fn mark_received(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<()> {
+        self.update_status(message_id, room_id, AckStatus::Received)
+            .await
+    }
+
+    pub async fn mark_persisted(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+        seq: i64,
+    ) -> ChannelResult<()> {
+        let key = format!("ack:pending:{}:{}", room_id, message_id);
+        let ack = MessageAck {
+            message_id,
+            room_id,
+            seq,
+            status: AckStatus::Persisted,
+            timestamp: chrono::Utc::now(),
+        };
+        self.set_with_ttl(&key, &ack).await?;
+        Ok(())
+    }
+
+    pub async fn mark_delivered(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<()> {
+        self.update_status(message_id, room_id, AckStatus::Delivered)
+            .await?;
+        let key = format!("ack:pending:{}:{}", room_id, message_id);
+        self.cache.remove(&key).await?;
+        Ok(())
+    }
+
+    pub async fn mark_failed(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<()> {
+        self.update_status(message_id, room_id, AckStatus::Failed)
+            .await
+    }
+
+    pub async fn get_status(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<Option<MessageAck>> {
+        let key = format!("ack:pending:{}:{}", room_id, message_id);
+        Ok(self.cache.get::<MessageAck>(&key).await?)
+    }
+
+    async fn update_status(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+        status: AckStatus,
+    ) -> ChannelResult<()> {
+        if let Some(mut ack) = self.get_status(message_id, room_id).await? {
+            ack.status = status;
+            ack.timestamp = chrono::Utc::now();
+            let key = format!("ack:pending:{}:{}", room_id, message_id);
+            self.set_with_ttl(&key, &ack).await?;
+        }
+        Ok(())
+    }
+}
diff --git a/lib/channel/bus.rs b/lib/channel/bus.rs
new file mode 100644
index 0000000..c412da9
--- /dev/null
+++ b/lib/channel/bus.rs
@@ -0,0 +1,608 @@
+use std::{
+    collections::{HashMap, HashSet},
+    sync::Arc,
+};
+
+use cache::AppCache;
+use dashmap::DashMap;
+use db::AppDatabase;
+use model::room::RoomMessageModel;
+use serde::Deserialize;
+use serde::Serialize;
+use socketio::{Socket, SocketIo};
+use tokio::sync::{Mutex, RwLock};
+use tracing::warn;
+use uuid::Uuid;
+
+use crate::{
+    ChannelBusConfig, ChannelError, ChannelResult,
+    circuit_breaker::CircuitBreaker,
+    dedup::DeduplicationManager,
+    event::ChannelEvent,
+    metrics::ChannelMetrics,
+    reconnect::ReconnectManager,
+    rooms::{
+        active_workspace_users, catchup_messages, refresh_user_rooms_cache,
+        room_socket_name, room_workspace, user_rooms,
+    },
+    security::{CsrfProtection, RateLimiter},
+    seq::SeqAllocator,
+};
+
+const ROOM_MESSAGE_EVENT: &str = "room.message";
+
+#[derive(Clone)]
+pub struct ChannelBus {
+    pub(crate) inner: Arc<Inner>,
+}
+
+pub(crate) struct Inner {
+    pub(crate) db: AppDatabase,
+    pub(crate) cache: AppCache,
+    pub(crate) io: SocketIo,
+    pub(crate) config: ChannelBusConfig,
+    pub(crate) online: RwLock<HashMap<Uuid, HashMap<String, Socket>>>,
+    pub(crate) user_sync_locks: DashMap<Uuid, Arc<Mutex<()>>>,
+    pub(crate) typing_states: DashMap<(Uuid, Uuid), (crate::event::UserInfo, crate::event::RoomInfo, tokio_util::sync::CancellationToken)>,
+    pub(crate) seq: SeqAllocator,
+    pub(crate) dedup: DeduplicationManager,
+    pub(crate) metrics: ChannelMetrics,
+    pub(crate) reconnect: ReconnectManager,
+    pub(crate) rate_limiter: RateLimiter,
+    pub(crate) csrf: CsrfProtection,
+    pub(crate) circuit_breaker: CircuitBreaker,
+}
+
+#[derive(Debug, Deserialize)]
+struct ConnectAuth {
+    #[serde(default)]
+    last_seq: HashMap<Uuid, i64>,
+}
+
+impl ChannelBus {
+    pub fn io(&self) -> &SocketIo {
+        &self.inner.io
+    }
+    pub async fn first_workspace_id(
+        &self,
+        user: Uuid,
+    ) -> ChannelResult<Option<Uuid>> {
+        let row = db::sqlx::query_as::<_, (Uuid,)>(
+            "SELECT wk FROM wk_member WHERE \"user\" = $1 AND leave_at IS NULL LIMIT 1",
+        )
+        .bind(user)
+        .fetch_optional(self.inner.db.reader())
+        .await?;
+        Ok(row.map(|r| r.0))
+    }
+    pub async fn lookup_room(
+        &self,
+        room: Uuid,
+    ) -> ChannelResult<crate::event::RoomInfo> {
+        let row = db::sqlx::query_as::<_, (String,)>( 
+            "SELECT name FROM room WHERE id = $1",
+        )
+        .bind(room)
+        .fetch_optional(self.inner.db.reader())
+        .await?
+        .map(|(name,)| name)
+        .unwrap_or_default();
+        Ok(crate::event::RoomInfo {
+            id: room,
+            name: row,
+        })
+    }
+    pub async fn list_workspace_members(
+        &self,
+        workspace: Uuid,
+    ) -> ChannelResult<Vec<(Uuid, String, String, String)>> {
+        let rows = db::sqlx::query_as::<_, (Uuid, String, String, String)>(
+            r#"SELECT u.id, u.username, u.display_name, u.avatar_url
+               FROM wk_member wm
+               JOIN "user" u ON u.id = wm."user"
+               WHERE wm.wk = $1 AND wm.leave_at IS NULL
+               ORDER BY u.username"#,
+        )
+        .bind(workspace)
+        .fetch_all(self.inner.db.reader())
+        .await?;
+        Ok(rows)
+    }
+    pub async fn lookup_workspace(
+        &self,
+        wk: Uuid,
+    ) -> ChannelResult<crate::event::WorkspaceInfo> {
+        use db::sqlx::Row;
+        let row = db::sqlx::query(
+            "SELECT name, avatar_url FROM workspace WHERE id = $1",
+        )
+        .bind(wk)
+        .fetch_optional(self.inner.db.reader())
+        .await?;
+        let (name, avatar_url) = match row {
+            Some(r) => (r.get::<String, _>(0), r.get::<String, _>(1)),
+            None => (String::new(), String::new()),
+        };
+        Ok(crate::event::WorkspaceInfo {
+            id: wk,
+            name,
+            avatar_url,
+        })
+    }
+    pub async fn lookup_users(
+        &self,
+        users: &[Uuid],
+    ) -> ChannelResult<std::collections::HashMap<Uuid, crate::event::UserInfo>> {
+        if users.is_empty() {
+            return Ok(std::collections::HashMap::new());
+        }
+        let rows = db::sqlx::query_as::<_, model::users::UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, \
+             allow_use, can_search, last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE id = ANY($1)",
+        )
+        .bind(users)
+        .fetch_all(self.inner.db.reader())
+        .await?;
+        Ok(rows
+            .into_iter()
+            .map(|m| (m.id, crate::event::UserInfo::from_model(&m)))
+            .collect())
+    }
+    pub async fn lookup_user(
+        &self,
+        user: Uuid,
+    ) -> ChannelResult<crate::event::UserInfo> {
+        let row = db::sqlx::query_as::<_, model::users::UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, \
+             allow_use, can_search, last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE id = $1",
+        )
+        .bind(user)
+        .fetch_optional(self.inner.db.reader())
+        .await?
+        .map(|m| crate::event::UserInfo::from_model(&m))
+        .unwrap_or_else(|| crate::event::UserInfo::unknown(user));
+        Ok(row)
+    }
+    pub async fn list_user_rooms(
+        &self,
+        user: Uuid,
+    ) -> ChannelResult<Vec<crate::rooms::RoomListItem>> {
+        crate::rooms::user_rooms_for_api(
+            &self.inner.db,
+            &self.inner.cache,
+            &self.inner.config,
+            user,
+        )
+        .await
+    }
+    pub async fn list_user_categories(
+        &self,
+        user: Uuid,
+    ) -> ChannelResult<Vec<crate::rooms::CategoryListItem>> {
+        crate::rooms::user_categories_for_api(
+            &self.inner.db,
+            &self.inner.cache,
+            &self.inner.config,
+            user,
+        )
+        .await
+    }
+
+    pub fn new(
+        db: AppDatabase,
+        cache: AppCache,
+        io: SocketIo,
+        config: ChannelBusConfig,
+    ) -> Self {
+        let seq = match config.seq_segment_size {
+            Some(size) => {
+                SeqAllocator::with_segment_size(cache.clone(), db.clone(), size)
+            }
+            None => SeqAllocator::new(cache.clone(), db.clone()),
+        };
+        let dedup = DeduplicationManager::with_config(
+            cache.clone(),
+            std::time::Duration::from_secs(
+                config.dedup_window_secs.unwrap_or(300),
+            ),
+        );
+        let reconnect = ReconnectManager::new(cache.clone(), db.clone());
+        let rate_limiter = match (
+            config.rate_limit_max_requests,
+            config.rate_limit_window_secs,
+        ) {
+            (Some(max), Some(secs)) => RateLimiter::with_config(
+                cache.clone(),
+                max,
+                std::time::Duration::from_secs(secs),
+            ),
+            _ => RateLimiter::new(cache.clone()),
+        };
+        let csrf = CsrfProtection::new(cache.clone());
+        let circuit_breaker = match (
+            config.circuit_breaker_failure_threshold,
+            config.circuit_breaker_success_threshold,
+            config.circuit_breaker_timeout_secs,
+            config.circuit_breaker_half_open_max_calls,
+        ) {
+            (Some(failure), Some(success), Some(secs), Some(half_open)) => {
+                CircuitBreaker::with_config(
+                    failure,
+                    success,
+                    std::time::Duration::from_secs(secs),
+                    half_open,
+                )
+            }
+            _ => CircuitBreaker::new(),
+        };
+        Self {
+            inner: Arc::new(Inner {
+                db,
+                cache,
+                io,
+                config,
+                online: RwLock::new(HashMap::new()),
+                user_sync_locks: DashMap::new(),
+                typing_states: DashMap::new(),
+                seq,
+                dedup,
+                metrics: ChannelMetrics::new(),
+                reconnect,
+                rate_limiter,
+                csrf,
+                circuit_breaker,
+            }),
+        }
+    }
+
+    pub async fn attach(&self) -> ChannelResult<()> {
+        let namespace =
+            self.inner.io.namespace(&self.inner.config.namespace).await;
+
+        let auth_bus = self.clone();
+        namespace
+            .use_middleware(move |socket, auth| {
+                let bus = auth_bus.clone();
+                async move {
+                    if socket.session_user().is_some() {
+                        return Ok(());
+                    }
+                    let token = auth
+                        .as_ref()
+                        .and_then(|v| v.get("access_token"))
+                        .and_then(|v| v.as_str());
+                    if let Some(token) = token {
+                        let ctx = bus
+                            .check_access_token(token.to_owned())
+                            .await
+                            .map_err(|_| {
+                                socketio::SocketIoError::Adapter(
+                                    "token invalid or expired".to_owned(),
+                                )
+                            })?;
+                        socket.set_user(ctx.user_id);
+                        return Ok(());
+                    }
+                    Err(socketio::SocketIoError::Adapter(
+                        "unauthorized".to_owned(),
+                    ))
+                }
+            })
+            .await;
+
+        let on_connect_bus = self.clone();
+        namespace
+            .on_connect(move |socket| {
+                let bus = on_connect_bus.clone();
+                async move {
+                    bus.inner.metrics.increment_connections();
+                    if let Err(error) = bus.handle_connect(socket.clone()).await {
+                        warn!(%error, "channel socket connect failed, disconnecting");
+                        let _ = socket.disconnect().await;
+                    }
+                }
+            })
+            .await;
+
+        let on_disconnect_bus = self.clone();
+        namespace
+            .on_disconnect(move |socket, _reason| {
+                let bus = on_disconnect_bus.clone();
+                async move {
+                    bus.inner.metrics.decrement_connections();
+                    bus.handle_disconnect(&socket).await;
+                }
+            })
+            .await;
+        crate::http::ws::register_message_handler(self).await?;
+
+        Ok(())
+    }
+
+    pub async fn publish_room_message(
+        &self,
+        message: RoomMessageModel,
+        sender: Option<crate::event::UserInfo>,
+    ) -> ChannelResult<()> {
+        let is_new = self
+            .inner
+            .dedup
+            .check_and_mark(message.id, message.room)
+            .await?;
+        if !is_new {
+            return Ok(());
+        }
+        let event = match sender {
+            Some(s) => ChannelEvent::message_created_with_sender(message, s),
+            None => ChannelEvent::message_created(message),
+        };
+        self.publish_event(event).await
+    }
+
+    pub async fn publish_room_event<T>(
+        &self,
+        room: Uuid,
+        event_type: impl Into<String>,
+        payload: T,
+    ) -> ChannelResult<()>
+    where
+        T: Serialize,
+    {
+        let payload = serde_json::to_value(payload)?;
+        self.publish_event(ChannelEvent::custom(room, event_type, payload))
+            .await
+    }
+    pub async fn emit_to_user<T: Serialize>(
+        &self,
+        user: Uuid,
+        event: &str,
+        data: &T,
+    ) -> ChannelResult<()> {
+        let sockets = self
+            .inner
+            .online
+            .read()
+            .await
+            .get(&user)
+            .map(|sockets| sockets.values().cloned().collect::<Vec<_>>())
+            .unwrap_or_default();
+
+        for socket in sockets {
+            socket.emit(event, data).await?;
+        }
+        Ok(())
+    }
+
+    pub async fn refresh_user(&self, user: Uuid) -> ChannelResult<()> {
+        let rooms = refresh_user_rooms_cache(
+            &self.inner.db,
+            &self.inner.cache,
+            &self.inner.config,
+            user,
+        )
+        .await?;
+        self.sync_online_user_rooms(user, &rooms).await
+    }
+
+    pub async fn workspace_changed(&self, wk: Uuid) -> ChannelResult<()> {
+        let users = active_workspace_users(&self.inner.db, wk).await?;
+        let bus = self.clone();
+        let results =
+            futures::future::join_all(users.into_iter().map(|user| {
+                let bus = bus.clone();
+                async move { bus.refresh_user(user).await }
+            }))
+            .await;
+        let mut first_error = None;
+        for result in results {
+            if let Err(e) = result {
+                tracing::warn!(error = %e, "workspace refresh failed for user");
+                if first_error.is_none() {
+                    first_error = Some(e);
+                }
+            }
+        }
+        if let Some(e) = first_error {
+            Err(e)
+        } else {
+            Ok(())
+        }
+    }
+
+    pub async fn room_changed(&self, room: Uuid) -> ChannelResult<()> {
+        if let Some(wk) = room_workspace(&self.inner.db, room).await? {
+            self.workspace_changed(wk).await?;
+        }
+        Ok(())
+    }
+
+    async fn publish_event(&self, event: ChannelEvent) -> ChannelResult<()> {
+        self.inner.metrics.increment_sent();
+
+        let result = self
+            .inner
+            .circuit_breaker
+            .call(async {
+                self.inner
+                    .io
+                    .namespace(&self.inner.config.namespace)
+                    .await
+                    .to(room_socket_name(event.room))
+                    .emit(ROOM_MESSAGE_EVENT, event)
+                    .await
+                    .map_err(ChannelError::SocketIo)
+            })
+            .await;
+
+        match result {
+            Ok(()) => {
+                self.inner.metrics.increment_received();
+                Ok(())
+            }
+            Err(e) => {
+                self.inner.metrics.increment_failed();
+                match e {
+                    crate::circuit_breaker::CircuitBreakerError::Open => {
+                        Err(ChannelError::Internal(
+                            "circuit breaker open".to_string(),
+                        ))
+                    }
+                    crate::circuit_breaker::CircuitBreakerError::Inner(e) => {
+                        Err(e)
+                    }
+                }
+            }
+        }
+    }
+
+    async fn handle_connect(&self, socket: Socket) -> ChannelResult<()> {
+        let user = socket.session_user().ok_or(ChannelError::Unauthorized)?;
+
+        if !self
+            .inner
+            .rate_limiter
+            .check_rate_limit(user, "connect")
+            .await?
+        {
+            return Err(ChannelError::RateLimitExceeded);
+        }
+
+        let auth = socket
+            .auth()
+            .await
+            .and_then(|value| serde_json::from_value::<ConnectAuth>(value).ok())
+            .unwrap_or_else(|| ConnectAuth {
+                last_seq: HashMap::new(),
+            });
+        let rooms = user_rooms(
+            &self.inner.db,
+            &self.inner.cache,
+            &self.inner.config,
+            user,
+        )
+        .await?;
+
+        for room in &rooms {
+            socket.join(room_socket_name(*room)).await?;
+        }
+        self.register_socket(user, socket.clone()).await;
+        self.catchup(&socket, &rooms, &auth.last_seq).await?;
+        Ok(())
+    }
+
+    async fn handle_disconnect(&self, socket: &Socket) {
+        let Some(user) = socket.session_user() else {
+            return;
+        };
+        let rooms = socket.rooms().await;
+        for room_name in &rooms {
+            if let Some(room_str) = room_name.strip_prefix("room:") {
+                if let Ok(room_id) = Uuid::parse_str(room_str) {
+                    let _ = self.publish_room_event(
+                        room_id,
+                        "voice.channel_left",
+                        serde_json::json!({"user_id": user, "disconnected": true}),
+                    )
+                    .await;
+                }
+            }
+        }
+        let mut online = self.inner.online.write().await;
+        if let Some(sockets) = online.get_mut(&user) {
+            sockets.remove(socket.id());
+            if sockets.is_empty() {
+                online.remove(&user);
+                self.inner.user_sync_locks.remove(&user);
+            }
+        }
+    }
+
+    async fn register_socket(&self, user: Uuid, socket: Socket) {
+        self.inner
+            .online
+            .write()
+            .await
+            .entry(user)
+            .or_default()
+            .insert(socket.id().to_owned(), socket);
+    }
+
+    async fn sync_online_user_rooms(
+        &self,
+        user: Uuid,
+        desired_rooms: &[Uuid],
+    ) -> ChannelResult<()> {
+        let lock = self
+            .inner
+            .user_sync_locks
+            .entry(user)
+            .or_insert_with(|| Arc::new(Mutex::new(())))
+            .clone();
+        let _guard = lock.lock().await;
+
+        let sockets = self
+            .inner
+            .online
+            .read()
+            .await
+            .get(&user)
+            .map(|sockets| sockets.values().cloned().collect::<Vec<_>>())
+            .unwrap_or_default();
+
+        let desired = desired_rooms
+            .iter()
+            .map(|room| room_socket_name(*room))
+            .collect::<HashSet<_>>();
+
+        for socket in sockets {
+            let current = socket
+                .rooms()
+                .await
+                .into_iter()
+                .filter(|room| room.starts_with("room:"))
+                .collect::<HashSet<_>>();
+
+            for room in desired.difference(&current) {
+                socket.join(room.clone()).await?;
+            }
+            for room in current.difference(&desired) {
+                socket.leave(room).await?;
+            }
+        }
+        Ok(())
+    }
+
+    async fn catchup(
+        &self,
+        socket: &Socket,
+        rooms: &[Uuid],
+        last_seq: &HashMap<Uuid, i64>,
+    ) -> ChannelResult<()> {
+        for room in rooms {
+            let Some(seq) = last_seq.get(room) else {
+                continue;
+            };
+            let messages = catchup_messages(
+                &self.inner.db,
+                &self.inner.config,
+                *room,
+                *seq,
+            )
+            .await?;
+            for message in messages {
+                let sender = match self.lookup_user(message.author).await {
+                    Ok(s) => Some(s),
+                    Err(_) => None,
+                };
+                let event = match sender {
+                    Some(s) => ChannelEvent::message_created_with_sender(message, s),
+                    None => ChannelEvent::message_created(message),
+                };
+                socket.emit(ROOM_MESSAGE_EVENT, event).await?;
+            }
+        }
+        Ok(())
+    }
+}
diff --git a/lib/channel/cdn.rs b/lib/channel/cdn.rs
new file mode 100644
index 0000000..08c26d1
--- /dev/null
+++ b/lib/channel/cdn.rs
@@ -0,0 +1,136 @@
+use std::time::Duration;
+use uuid::Uuid;
+
+use storage::ObjectStorage;
+
+use crate::{ChannelError, ChannelResult};
+
+const ATTACHMENT_KEY_PREFIX: &str = "attachments";
+const DEFAULT_PRESIGNED_TTL: Duration = Duration::from_secs(3600);
+const DEFAULT_MAX_FILE_SIZE: u64 = 50 * 1024 * 1024; // 50 MB
+
+#[derive(Clone)]
+pub struct CdnManager {
+    storage: storage::AppStorage,
+    presigned_ttl: Duration,
+    max_file_size: u64,
+}
+
+impl CdnManager {
+    pub fn new(storage: storage::AppStorage) -> Self {
+        Self {
+            storage,
+            presigned_ttl: DEFAULT_PRESIGNED_TTL,
+            max_file_size: DEFAULT_MAX_FILE_SIZE,
+        }
+    }
+
+    pub fn with_config(
+        storage: storage::AppStorage,
+        presigned_ttl: Duration,
+        max_file_size: u64,
+    ) -> Self {
+        Self {
+            storage,
+            presigned_ttl,
+            max_file_size,
+        }
+    }
+
+    pub fn max_file_size(&self) -> u64 {
+        self.max_file_size
+    }
+
+    pub async fn upload_file(
+        &self,
+        room_id: Uuid,
+        message_id: Uuid,
+        file_data: &[u8],
+        filename: &str,
+        content_type: Option<String>,
+    ) -> ChannelResult<CdnStoredFile> {
+        if file_data.len() as u64 > self.max_file_size {
+            return Err(ChannelError::Internal(
+                "file exceeds max size".to_string(),
+            ));
+        }
+
+        let filename = sanitize_filename(filename);
+        let key = format!(
+            "{}/{}/{}/{}",
+            ATTACHMENT_KEY_PREFIX, room_id, message_id, filename
+        );
+
+        let options = storage::PutObjectOptions {
+            content_type,
+            content_length: Some(file_data.len() as i64),
+            cache_control: Some("public, max-age=86400".to_string()),
+        };
+
+        let stored = self
+            .storage
+            .put_bytes(&key, file_data.to_vec(), options)
+            .await?;
+
+        Ok(CdnStoredFile {
+            key: stored.key,
+            url: stored.url,
+            e_tag: stored.e_tag,
+            size: file_data.len() as i64,
+        })
+    }
+
+    pub async fn get_file(&self, key: &str) -> ChannelResult<CdnFileContent> {
+        let object = self.storage.get_bytes(key).await?;
+        Ok(CdnFileContent {
+            bytes: object.bytes,
+            content_type: object.content_type,
+            content_length: object.content_length,
+        })
+    }
+
+    pub async fn delete_file(&self, key: &str) -> ChannelResult<()> {
+        self.storage.delete(key).await?;
+        Ok(())
+    }
+
+    pub fn public_url(&self, key: &str) -> ChannelResult<Option<String>> {
+        self.storage.public_url(key).map_err(Into::into)
+    }
+
+    pub async fn presigned_url(&self, key: &str) -> ChannelResult<String> {
+        Ok(self
+            .storage
+            .presigned_get_url(key, self.presigned_ttl)
+            .await?)
+    }
+}
+fn sanitize_filename(name: &str) -> String {
+    let cleaned: String = name
+        .chars()
+        .filter(|&c| c.is_ascii_graphic() && c != '/' && c != '\\' && c != '\0')
+        .take(255)
+        .collect::<String>()
+        .trim()
+        .to_owned();
+    if cleaned.is_empty() {
+        uuid::Uuid::new_v4().to_string()
+    } else {
+        cleaned
+    }
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct CdnStoredFile {
+    pub key: String,
+    pub url: String,
+    pub e_tag: Option<String>,
+    pub size: i64,
+}
+
+#[derive(Debug)]
+pub struct CdnFileContent {
+    pub bytes: Vec<u8>,
+    pub content_type: Option<String>,
+    pub content_length: Option<i64>,
+}
diff --git a/lib/channel/circuit_breaker.rs b/lib/channel/circuit_breaker.rs
new file mode 100644
index 0000000..e9dc288
--- /dev/null
+++ b/lib/channel/circuit_breaker.rs
@@ -0,0 +1,165 @@
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio::sync::Mutex;
+
+use crate::ChannelError;
+
+const STATUS_CLOSED: u8 = 0;
+const STATUS_OPEN: u8 = 1;
+const STATUS_HALF_OPEN: u8 = 2;
+
+#[derive(Clone)]
+pub struct CircuitBreaker {
+    inner: Arc<Inner>,
+}
+
+struct CircuitState {
+    status: u8,
+    failure_count: u32,
+    success_count: u32,
+    half_open_calls: u32,
+    last_failure_time: Option<Instant>,
+}
+
+struct Inner {
+    state: Mutex<CircuitState>,
+    config: CircuitConfig,
+}
+
+#[derive(Clone)]
+struct CircuitConfig {
+    failure_threshold: u32,
+    success_threshold: u32,
+    timeout: Duration,
+    half_open_max_calls: u32,
+}
+
+impl CircuitBreaker {
+    pub fn new() -> Self {
+        Self::with_config(5, 2, Duration::from_secs(60), 3)
+    }
+
+    pub fn with_config(
+        failure_threshold: u32,
+        success_threshold: u32,
+        timeout: Duration,
+        half_open_max_calls: u32,
+    ) -> Self {
+        Self {
+            inner: Arc::new(Inner {
+                state: Mutex::new(CircuitState {
+                    status: STATUS_CLOSED,
+                    failure_count: 0,
+                    success_count: 0,
+                    half_open_calls: 0,
+                    last_failure_time: None,
+                }),
+                config: CircuitConfig {
+                    failure_threshold,
+                    success_threshold,
+                    timeout,
+                    half_open_max_calls,
+                },
+            }),
+        }
+    }
+
+    pub async fn call<F, T>(&self, f: F) -> Result<T, CircuitBreakerError>
+    where
+        F: std::future::Future<Output = Result<T, ChannelError>>,
+    {
+        let slot_reserved = {
+            let mut state = self.inner.state.lock().await;
+            match state.status {
+                STATUS_OPEN => {
+                    match state.last_failure_time {
+                        Some(t) if t.elapsed() > self.inner.config.timeout => {
+                            state.status = STATUS_HALF_OPEN;
+                            state.half_open_calls = 1;
+                            state.success_count = 0;
+                            true
+                        }
+                        _ => false,
+                    }
+                }
+                STATUS_HALF_OPEN => {
+                    if state.half_open_calls
+                        < self.inner.config.half_open_max_calls
+                    {
+                        state.half_open_calls += 1;
+                        true
+                    } else {
+                        false
+                    }
+                }
+                _ => true, // Closed → allow
+            }
+        }; // Lock released before executing the call.
+
+        if !slot_reserved {
+            return Err(CircuitBreakerError::Open);
+        }
+
+        match f.await {
+            Ok(result) => {
+                self.on_success().await;
+                Ok(result)
+            }
+            Err(e) => {
+                self.on_failure().await;
+                Err(CircuitBreakerError::Inner(e))
+            }
+        }
+    }
+
+    async fn on_success(&self) {
+        let mut state = self.inner.state.lock().await;
+        state.failure_count = 0;
+
+        if state.status == STATUS_HALF_OPEN {
+            state.success_count += 1;
+            if state.success_count >= self.inner.config.success_threshold {
+                state.status = STATUS_CLOSED;
+                state.success_count = 0;
+                state.half_open_calls = 0;
+            }
+        }
+    }
+    async fn on_failure(&self) {
+        let mut state = self.inner.state.lock().await;
+        state.failure_count += 1;
+        state.last_failure_time = Some(Instant::now());
+
+        if state.status == STATUS_HALF_OPEN {
+            state.status = STATUS_OPEN;
+            state.success_count = 0;
+            state.half_open_calls = 0;
+        } else if state.status == STATUS_CLOSED
+            && state.failure_count >= self.inner.config.failure_threshold
+        {
+            state.status = STATUS_OPEN;
+        }
+    }
+
+    pub async fn is_open(&self) -> bool {
+        let state = self.inner.state.lock().await;
+        state.status == STATUS_OPEN
+    }
+}
+
+#[derive(Debug)]
+pub enum CircuitBreakerError {
+    Open,
+    Inner(ChannelError),
+}
+
+impl std::fmt::Display for CircuitBreakerError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            CircuitBreakerError::Open => write!(f, "Circuit breaker is open"),
+            CircuitBreakerError::Inner(e) => write!(f, "{}", e),
+        }
+    }
+}
+
+impl std::error::Error for CircuitBreakerError {}
diff --git a/lib/channel/config.rs b/lib/channel/config.rs
new file mode 100644
index 0000000..1781791
--- /dev/null
+++ b/lib/channel/config.rs
@@ -0,0 +1,38 @@
+#[derive(Clone, Debug)]
+pub struct ChannelBusConfig {
+    pub namespace: String,
+    pub room_cache_ttl_hint: Option<std::time::Duration>,
+    pub catchup_limit: i64,
+    pub signing_secret: Option<String>,
+    pub seq_segment_size: Option<u64>,
+    pub rate_limit_max_requests: Option<u32>,
+    pub rate_limit_window_secs: Option<u64>,
+    pub dedup_window_secs: Option<u64>,
+    pub ack_timeout_secs: Option<u64>,
+    pub revoke_window_secs: Option<u64>,
+    pub circuit_breaker_failure_threshold: Option<u32>,
+    pub circuit_breaker_success_threshold: Option<u32>,
+    pub circuit_breaker_timeout_secs: Option<u64>,
+    pub circuit_breaker_half_open_max_calls: Option<u32>,
+}
+
+impl Default for ChannelBusConfig {
+    fn default() -> Self {
+        Self {
+            namespace: "/channel".to_owned(),
+            room_cache_ttl_hint: Some(std::time::Duration::from_secs(300)),
+            catchup_limit: 100,
+            signing_secret: None,
+            seq_segment_size: None,
+            rate_limit_max_requests: None,
+            rate_limit_window_secs: None,
+            dedup_window_secs: None,
+            ack_timeout_secs: None,
+            revoke_window_secs: None,
+            circuit_breaker_failure_threshold: None,
+            circuit_breaker_success_threshold: None,
+            circuit_breaker_timeout_secs: None,
+            circuit_breaker_half_open_max_calls: None,
+        }
+    }
+}
diff --git a/lib/channel/dedup.rs b/lib/channel/dedup.rs
new file mode 100644
index 0000000..3eeab2e
--- /dev/null
+++ b/lib/channel/dedup.rs
@@ -0,0 +1,55 @@
+use std::time::Duration;
+use uuid::Uuid;
+
+use crate::{ChannelError, ChannelResult, security::require_cluster};
+
+#[derive(Clone)]
+pub struct DeduplicationManager {
+    cache: cache::AppCache,
+    window: Duration,
+}
+
+impl DeduplicationManager {
+    pub fn new(cache: cache::AppCache) -> Self {
+        Self {
+            cache,
+            window: Duration::from_secs(300),
+        }
+    }
+
+    pub fn with_config(cache: cache::AppCache, window: Duration) -> Self {
+        Self { cache, window }
+    }
+
+    pub async fn check_and_mark(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<bool> {
+        let cluster = require_cluster(&self.cache)?;
+        let key = format!("dedup:{}:{}", room_id, message_id);
+        let mut conn = cluster.conn();
+
+        let result: Option<String> = redis::cmd("SET")
+            .arg(&key)
+            .arg("1")
+            .arg("NX")
+            .arg("EX")
+            .arg(self.window.as_secs())
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        Ok(result.is_some())
+    }
+
+    pub async fn is_duplicate(
+        &self,
+        message_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<bool> {
+        let cluster = require_cluster(&self.cache)?;
+        let key = format!("dedup:{}:{}", room_id, message_id);
+        Ok(cluster.exists(&key).await?)
+    }
+}
diff --git a/lib/channel/e2e.rs b/lib/channel/e2e.rs
new file mode 100644
index 0000000..cd57193
--- /dev/null
+++ b/lib/channel/e2e.rs
@@ -0,0 +1,36 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EncryptedMessage {
+    pub ciphertext: Vec<u8>,
+    pub nonce: Vec<u8>,
+    pub recipient_key_id: String,
+}
+
+pub struct E2EEncryption;
+
+impl E2EEncryption {
+    pub fn new() -> Self {
+        Self {}
+    }
+
+    pub fn encrypt(
+        &self,
+        _plaintext: &[u8],
+        _recipient_public_key: &[u8],
+    ) -> crate::ChannelResult<EncryptedMessage> {
+        Err(crate::ChannelError::Internal(
+            "e2e not implemented".to_string(),
+        ))
+    }
+
+    pub fn decrypt(
+        &self,
+        _encrypted: &EncryptedMessage,
+        _private_key: &[u8],
+    ) -> crate::ChannelResult<Vec<u8>> {
+        Err(crate::ChannelError::Internal(
+            "e2e not implemented".to_string(),
+        ))
+    }
+}
diff --git a/lib/channel/envelope.rs b/lib/channel/envelope.rs
new file mode 100644
index 0000000..be4b919
--- /dev/null
+++ b/lib/channel/envelope.rs
@@ -0,0 +1,37 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ChannelEnvelope<T> {
+    #[serde(default = "uuid::Uuid::now_v7")]
+    pub message_id: Uuid,
+    pub user_id: Uuid,
+    pub payload: T,
+    #[serde(default = "default_timestamp")]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[serde(default)]
+    pub attempt: u8,
+}
+
+fn default_timestamp() -> chrono::DateTime<chrono::Utc> {
+    chrono::Utc::now()
+}
+
+impl<T> ChannelEnvelope<T> {
+    pub fn new(user_id: Uuid, payload: T) -> Self {
+        Self {
+            message_id: Uuid::now_v7(),
+            user_id,
+            payload,
+            created_at: chrono::Utc::now(),
+            attempt: 1,
+        }
+    }
+
+    pub fn retry(self) -> Self {
+        Self {
+            attempt: self.attempt + 1,
+            ..self
+        }
+    }
+}
diff --git a/lib/channel/error.rs b/lib/channel/error.rs
new file mode 100644
index 0000000..e6773ef
--- /dev/null
+++ b/lib/channel/error.rs
@@ -0,0 +1,66 @@
+#[derive(Debug, thiserror::Error)]
+pub enum ChannelError {
+    #[error("unauthorized")]
+    Unauthorized,
+    #[error("token invalid or expired")]
+    TokenInvalidOrExpired,
+    #[error("renewal limit exceeded")]
+    RenewalLimitExceeded,
+    #[error("rate limit exceeded")]
+    RateLimitExceeded,
+    #[error("room not found")]
+    RoomNotFound,
+    #[error("user not found")]
+    UserNotFound,
+    #[error("access denied")]
+    AccessDenied,
+    #[error("validation failed: {0}")]
+    Validation(String),
+    #[error("internal error: {0}")]
+    Internal(String),
+    #[error("database failed: {0}")]
+    Database(#[from] db::sqlx::Error),
+    #[error("cache failed: {0}")]
+    Cache(#[from] cache::CacheError),
+    #[error("socket.io failed: {0}")]
+    SocketIo(#[from] socketio::SocketIoError),
+    #[error("serialization failed: {0}")]
+    Serialization(#[from] serde_json::Error),
+    #[error("redis failed: {0}")]
+    Redis(#[from] redis::RedisError),
+    #[error("storage failed: {0}")]
+    Storage(#[from] storage::StorageError),
+}
+
+impl ChannelError {
+    pub fn ws_error_code(&self) -> (u16, &'static str) {
+        match self {
+            ChannelError::Unauthorized => (401, "unauthorized"),
+            ChannelError::TokenInvalidOrExpired => (401, "token_invalid"),
+            ChannelError::AccessDenied => (403, "access_denied"),
+            ChannelError::Validation(_) => (422, "validation_failed"),
+            ChannelError::RateLimitExceeded => (429, "rate_limit_exceeded"),
+            ChannelError::RoomNotFound => (404, "not_found"),
+            ChannelError::UserNotFound => (404, "user_not_found"),
+            ChannelError::RenewalLimitExceeded => (429, "renewal_limit"),
+            ChannelError::Internal(_) => (500, "internal_error"),
+            ChannelError::Database(_) => (500, "internal_error"),
+            ChannelError::Cache(_) => (500, "internal_error"),
+            ChannelError::SocketIo(_) => (500, "internal_error"),
+            ChannelError::Serialization(_) => (500, "internal_error"),
+            ChannelError::Redis(_) => (500, "internal_error"),
+            ChannelError::Storage(_) => (500, "internal_error"),
+        }
+    }
+
+    pub fn to_ws_error(&self) -> crate::http::out_event::WsError {
+        let (code, error_type) = self.ws_error_code();
+        crate::http::out_event::WsError {
+            code: code as i32,
+            error: error_type.to_string(),
+            message: self.to_string(),
+        }
+    }
+}
+
+pub type ChannelResult<T> = Result<T, ChannelError>;
diff --git a/lib/channel/event/ai.rs b/lib/channel/event/ai.rs
new file mode 100644
index 0000000..97fc4e2
--- /dev/null
+++ b/lib/channel/event/ai.rs
@@ -0,0 +1,44 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{AgentInfo, RoomInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AiAgentJoinedService {
+    pub room: RoomInfo,
+    pub agent: AgentInfo,
+    pub joined_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AiAgentLeftService {
+    pub room: RoomInfo,
+    pub agent: AgentInfo,
+    pub left_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomAiEntry {
+    pub agent_session: Uuid,
+    pub name: String,
+    pub agent_kind: String,
+    pub model_version: Option<Uuid>,
+    pub enabled: bool,
+    pub auto_reply: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomAiListService {
+    pub room: RoomInfo,
+    pub agents: Vec<RoomAiEntry>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AiAgentStatusChangedService {
+    pub room: RoomInfo,
+    pub agent: AgentInfo,
+    pub old_status: String,
+    pub new_status: String,
+    pub changed_at: DateTime<Utc>,
+}
diff --git a/lib/channel/event/attachment.rs b/lib/channel/event/attachment.rs
new file mode 100644
index 0000000..57f863e
--- /dev/null
+++ b/lib/channel/event/attachment.rs
@@ -0,0 +1,55 @@
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+use crate::event::{RoomInfo, UserInfo};
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AttachmentEventType {
+    Uploaded,
+    ThumbnailGenerated,
+    Deleted,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum AttachmentEvent {
+    #[serde(rename = "attachment.uploaded")]
+    Uploaded(AttachmentUploadedService),
+    #[serde(rename = "attachment.thumbnail_generated")]
+    ThumbnailGenerated(AttachmentThumbnailService),
+    #[serde(rename = "attachment.deleted")]
+    Deleted(AttachmentDeletedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AttachmentUploadedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub filename: String,
+    pub content_type: Option<String>,
+    pub size: i64,
+    pub url: Option<String>,
+    pub uploaded_by: Uuid,
+    pub uploaded_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AttachmentThumbnailService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub thumbnail_url: String,
+    pub width: i32,
+    pub height: i32,
+    pub generated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AttachmentDeletedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub deleted_by: UserInfo,
+    pub deleted_at: DateTime<Utc>,
+}
diff --git a/lib/channel/event/ban.rs b/lib/channel/event/ban.rs
new file mode 100644
index 0000000..cdf3bc7
--- /dev/null
+++ b/lib/channel/event/ban.rs
@@ -0,0 +1,52 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::event::{UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum BanEventType {
+    Banned,
+    Unbanned,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum BanEvent {
+    #[serde(rename = "ban.banned")]
+    Banned(BannedService),
+    #[serde(rename = "ban.unbanned")]
+    Unbanned(UnbannedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BannedService {
+    pub workspace: WorkspaceInfo,
+    pub user: UserInfo,
+    pub banned_by: UserInfo,
+    pub reason: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub banned_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct UnbannedService {
+    pub workspace: WorkspaceInfo,
+    pub user: UserInfo,
+    pub unbanned_by: UserInfo,
+    pub unbanned_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BanCreateClient {
+    pub workspace: WorkspaceInfo,
+    pub user: UserInfo,
+    pub reason: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BanRemoveClient {
+    pub workspace: WorkspaceInfo,
+    pub user: UserInfo,
+}
diff --git a/lib/channel/event/category.rs b/lib/channel/event/category.rs
new file mode 100644
index 0000000..c9c4260
--- /dev/null
+++ b/lib/channel/event/category.rs
@@ -0,0 +1,68 @@
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+use crate::event::{UserInfo, WorkspaceInfo};
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CategoryEventType {
+    Created,
+    Updated,
+    Deleted,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum CategoryEvent {
+    #[serde(rename = "category.created")]
+    Created(CategoryCreatedService),
+    #[serde(rename = "category.updated")]
+    Updated(CategoryUpdatedService),
+    #[serde(rename = "category.deleted")]
+    Deleted(CategoryDeletedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CategoryCreatedService {
+    pub id: Uuid,
+    #[serde(rename = "workspace")]
+    pub project: WorkspaceInfo,
+    pub name: String,
+    pub position: i32,
+    pub created_by: UserInfo,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CategoryUpdatedService {
+    pub id: Uuid,
+    #[serde(rename = "workspace")]
+    pub project: WorkspaceInfo,
+    pub name: Option<String>,
+    pub position: Option<i32>,
+    pub updated_by: UserInfo,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CategoryDeletedService {
+    pub id: Uuid,
+    #[serde(rename = "workspace")]
+    pub project: WorkspaceInfo,
+    pub deleted_by: UserInfo,
+    pub deleted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CategoryCreateClient {
+    pub project: WorkspaceInfo,
+    pub name: String,
+    pub position: i32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CategoryUpdateClient {
+    pub name: Option<String>,
+    pub position: Option<i32>,
+}
diff --git a/lib/channel/event/common.rs b/lib/channel/event/common.rs
new file mode 100644
index 0000000..ab7a7ea
--- /dev/null
+++ b/lib/channel/event/common.rs
@@ -0,0 +1,92 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct UserInfo {
+    pub id: Uuid,
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+}
+
+impl UserInfo {
+    pub fn unknown(id: Uuid) -> Self {
+        Self {
+            id,
+            username: String::new(),
+            display_name: String::new(),
+            avatar_url: String::new(),
+        }
+    }
+
+    pub fn from_model(m: &model::users::UserModel) -> Self {
+        Self {
+            id: m.id,
+            username: m.username.clone(),
+            display_name: m.display_name.clone(),
+            avatar_url: m.avatar_url.clone(),
+        }
+    }
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomInfo {
+    pub id: Uuid,
+    pub name: String,
+}
+
+impl RoomInfo {
+    pub fn unknown(id: Uuid) -> Self {
+        Self {
+            id,
+            name: String::new(),
+        }
+    }
+
+    pub fn from_model(m: &model::room::RoomModel) -> Self {
+        Self {
+            id: m.id,
+            name: m.name.clone(),
+        }
+    }
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceInfo {
+    pub id: Uuid,
+    pub name: String,
+    pub avatar_url: String,
+}
+
+impl WorkspaceInfo {
+    pub fn unknown(id: Uuid) -> Self {
+        Self {
+            id,
+            name: String::new(),
+            avatar_url: String::new(),
+        }
+    }
+
+    pub fn from_model(m: &model::workspace::WorkspaceModel) -> Self {
+        Self {
+            id: m.id,
+            name: m.name.clone(),
+            avatar_url: m.avatar_url.clone(),
+        }
+    }
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AgentInfo {
+    pub id: Uuid,
+    pub name: String,
+    pub agent_type: String,
+    pub model_name: Option<String>,
+}
+
+impl AgentInfo {
+    pub fn unknown(id: Uuid) -> Self {
+        Self {
+            id,
+            name: String::new(),
+            agent_type: String::new(),
+            model_name: None,
+        }
+    }
+}
diff --git a/lib/channel/event/conversation.rs b/lib/channel/event/conversation.rs
new file mode 100644
index 0000000..436b2a8
--- /dev/null
+++ b/lib/channel/event/conversation.rs
@@ -0,0 +1,123 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ConversationEventType {
+    Pinned,
+    Unpinned,
+    Muted,
+    Unmuted,
+    UnreadUpdated,
+    NotifyLevelChanged,
+}
+
+impl ConversationEventType {
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::Pinned => "conversation.pinned",
+            Self::Unpinned => "conversation.unpinned",
+            Self::Muted => "conversation.muted",
+            Self::Unmuted => "conversation.unmuted",
+            Self::UnreadUpdated => "conversation.unread_updated",
+            Self::NotifyLevelChanged => "conversation.notify_level_changed",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum ConversationEvent {
+    #[serde(rename = "conversation.pinned")]
+    Pinned(ConversationPinnedService),
+    #[serde(rename = "conversation.unpinned")]
+    Unpinned(ConversationUnpinnedService),
+    #[serde(rename = "conversation.muted")]
+    Muted(ConversationMutedService),
+    #[serde(rename = "conversation.unmuted")]
+    Unmuted(ConversationUnmutedService),
+    #[serde(rename = "conversation.unread_updated")]
+    UnreadUpdated(ConversationUnreadUpdatedService),
+    #[serde(rename = "conversation.notify_level_changed")]
+    NotifyLevelChanged(ConversationNotifyLevelChangedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationPinnedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub pinned_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationUnpinnedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub unpinned_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationMutedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub muted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationUnmutedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub unmuted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationUnreadUpdatedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub last_read_seq: i64,
+    pub unread_count: i64,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationNotifyLevelChangedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub old_level: String,
+    pub new_level: String,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationPinClient {
+    pub room: Uuid,
+    pub pin: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationMuteClient {
+    pub room: Uuid,
+    pub mute: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationNotifyLevelClient {
+    pub room: Uuid,
+    pub notify_level: String,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConversationSummary {
+    pub room: Uuid,
+    pub room_name: String,
+    pub room_type: String,
+    pub is_pinned: bool,
+    pub is_muted: bool,
+    pub notify_level: String,
+    pub last_read_seq: i64,
+    pub max_seq: i64,
+    pub unread_count: i64,
+    pub last_read_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/channel/event/dm.rs b/lib/channel/event/dm.rs
new file mode 100644
index 0000000..cbad446
--- /dev/null
+++ b/lib/channel/event/dm.rs
@@ -0,0 +1,66 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DmEventType {
+    Created,
+    Closed,
+    Reopened,
+}
+
+impl DmEventType {
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::Created => "dm.created",
+            Self::Closed => "dm.closed",
+            Self::Reopened => "dm.reopened",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum DmEvent {
+    #[serde(rename = "dm.created")]
+    Created(DmCreatedService),
+    #[serde(rename = "dm.closed")]
+    Closed(DmClosedService),
+    #[serde(rename = "dm.reopened")]
+    Reopened(DmReopenedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DmCreatedService {
+    pub room: RoomInfo,
+    pub initiator: UserInfo,
+    pub recipient: UserInfo,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DmClosedService {
+    pub room: RoomInfo,
+    pub closed_by: UserInfo,
+    pub closed_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DmReopenedService {
+    pub room: RoomInfo,
+    pub reopened_by: UserInfo,
+    pub reopened_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DmCreateClient {
+    pub recipient: Uuid,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DmCloseClient {
+    pub room: Uuid,
+}
diff --git a/lib/channel/event/draft.rs b/lib/channel/event/draft.rs
new file mode 100644
index 0000000..f708088
--- /dev/null
+++ b/lib/channel/event/draft.rs
@@ -0,0 +1,35 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DraftSavedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub content: String,
+    pub saved_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DraftClearedService {
+    pub user: UserInfo,
+    pub room: RoomInfo,
+    pub cleared_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DraftSaveClient {
+    pub room: RoomInfo,
+    pub content: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DraftLoadClient {
+    pub room: RoomInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DraftClearClient {
+    pub room: RoomInfo,
+}
diff --git a/lib/channel/event/forward.rs b/lib/channel/event/forward.rs
new file mode 100644
index 0000000..cd3a0e6
--- /dev/null
+++ b/lib/channel/event/forward.rs
@@ -0,0 +1,24 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageForwardedService {
+    pub id: Uuid,
+    pub seq: i64,
+    pub room: RoomInfo,
+    pub sender: UserInfo,
+    pub content: String,
+    pub content_type: String,
+    pub source_room: RoomInfo,
+    pub source_message_id: Uuid,
+    pub forwarded_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageForwardClient {
+    pub source_message_id: Uuid,
+    pub target_room: Uuid,
+}
diff --git a/lib/channel/event/invite.rs b/lib/channel/event/invite.rs
new file mode 100644
index 0000000..3bfb4c1
--- /dev/null
+++ b/lib/channel/event/invite.rs
@@ -0,0 +1,83 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum InviteEventType {
+    Created,
+    Accepted,
+    Rejected,
+    Revoked,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum InviteEvent {
+    #[serde(rename = "invite.created")]
+    Created(InviteCreatedService),
+    #[serde(rename = "invite.accepted")]
+    Accepted(InviteAcceptedService),
+    #[serde(rename = "invite.rejected")]
+    Rejected(InviteRejectedService),
+    #[serde(rename = "invite.revoked")]
+    Revoked(InviteRevokedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteCreatedService {
+    pub id: Uuid,
+    pub workspace: WorkspaceInfo,
+    pub room: Option<RoomInfo>,
+    pub inviter: UserInfo,
+    pub invitee: Option<UserInfo>,
+    pub code: String,
+    pub max_uses: Option<i32>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteAcceptedService {
+    pub id: Uuid,
+    pub workspace: WorkspaceInfo,
+    pub room: Option<RoomInfo>,
+    pub user: UserInfo,
+    pub accepted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteRejectedService {
+    pub id: Uuid,
+    pub workspace: WorkspaceInfo,
+    pub user: UserInfo,
+    pub rejected_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteRevokedService {
+    pub id: Uuid,
+    pub workspace: WorkspaceInfo,
+    pub revoked_by: UserInfo,
+    pub revoked_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteCreateClient {
+    pub workspace: WorkspaceInfo,
+    pub room: Option<Uuid>,
+    pub max_uses: Option<i32>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteAcceptClient {
+    pub code: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InviteRevokeClient {
+    pub id: Uuid,
+}
diff --git a/lib/channel/event/member.rs b/lib/channel/event/member.rs
new file mode 100644
index 0000000..ded684e
--- /dev/null
+++ b/lib/channel/event/member.rs
@@ -0,0 +1,89 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemberJoinedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub project_role: Option<String>,
+    pub joined_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MemberRemovedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub removed_by: UserInfo,
+    pub removed_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReadReceiptService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub last_read_seq: i64,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TypingStartService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub sender_type: String,
+    pub started_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TypingStopService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub sender_type: String,
+    pub stopped_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DndUpdatedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub do_not_disturb: bool,
+    pub dnd_start_hour: Option<i32>,
+    pub dnd_end_hour: Option<i32>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AccessGrantClient {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AccessRevokeClient {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReadReceiptClient {
+    pub room: RoomInfo,
+    pub last_read_seq: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TypingStartClient {
+    pub room: RoomInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TypingStopClient {
+    pub room: RoomInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DndUpdateClient {
+    pub room: RoomInfo,
+    pub do_not_disturb: bool,
+    pub dnd_start_hour: Option<i32>,
+    pub dnd_end_hour: Option<i32>,
+}
diff --git a/lib/channel/event/message.rs b/lib/channel/event/message.rs
new file mode 100644
index 0000000..ef70577
--- /dev/null
+++ b/lib/channel/event/message.rs
@@ -0,0 +1,106 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+use crate::event::reaction::ReactionGroup;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageNewService {
+    pub id: Uuid,
+    pub seq: i64,
+    pub room: RoomInfo,
+    pub sender_type: String,
+    pub sender: UserInfo,
+    pub thread: Option<Uuid>,
+    pub in_reply_to: Option<Uuid>,
+    pub content: String,
+    pub content_type: String,
+    #[serde(default)]
+    pub pinned: bool,
+    pub system_type: Option<String>,
+    #[serde(default)]
+    pub metadata: serde_json::Value,
+    pub thinking_content: Option<String>,
+    pub thinking_is_chunked: Option<bool>,
+    pub send_at: DateTime<Utc>,
+    #[serde(default)]
+    pub reactions: Vec<ReactionGroup>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageEditedService {
+    pub id: Uuid,
+    pub seq: i64,
+    pub room: RoomInfo,
+    pub sender: UserInfo,
+    pub content: String,
+    pub edited_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageRevokedService {
+    pub id: Uuid,
+    pub seq: i64,
+    pub room: RoomInfo,
+    pub revoked_by: UserInfo,
+    pub revoked_at: DateTime<Utc>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageStreamStartService {
+    pub message_id: Uuid,
+    pub room: RoomInfo,
+    pub sse_url: Option<String>,
+    pub display_name: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageStreamChunkService {
+    pub message_id: Uuid,
+    pub room: RoomInfo,
+    pub seq: i64,
+    pub content: String,
+    pub chunk_type: String,
+    pub display_name: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageStreamDoneService {
+    pub message_id: Uuid,
+    pub room: RoomInfo,
+    pub content: String,
+    pub thinking_content: Option<String>,
+    pub display_name: Option<String>,
+    pub error: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageListService {
+    pub room: RoomInfo,
+    pub messages: Vec<MessageNewService>,
+    pub total: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageSendClient {
+    pub room: Uuid,
+    pub content: String,
+    pub content_type: String,
+    pub thread: Option<Uuid>,
+    pub in_reply_to: Option<Uuid>,
+    pub attachment_ids: Option<Vec<Uuid>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageEditClient {
+    pub room: Uuid,
+    pub message_id: Uuid,
+    pub content: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageRevokeClient {
+    pub room: Uuid,
+    pub message_id: Uuid,
+}
diff --git a/lib/channel/event/message_read.rs b/lib/channel/event/message_read.rs
new file mode 100644
index 0000000..31b17fc
--- /dev/null
+++ b/lib/channel/event/message_read.rs
@@ -0,0 +1,45 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageReadService {
+    pub room: RoomInfo,
+    pub message_id: Uuid,
+    pub message_seq: i64,
+    pub reader: UserInfo,
+    pub read_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageReadBatchService {
+    pub room: RoomInfo,
+    pub message_ids: Vec<Uuid>,
+    pub last_seq: i64,
+    pub reader: UserInfo,
+    pub read_at: DateTime<Utc>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageReadersService {
+    pub message_id: Uuid,
+    pub readers: Vec<MessageReaderEntry>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageReaderEntry {
+    pub user: UserInfo,
+    pub read_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageMarkReadClient {
+    pub room: Uuid,
+    pub message_ids: Vec<Uuid>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageGetReadersClient {
+    pub message_id: Uuid,
+}
diff --git a/lib/channel/event/mod.rs b/lib/channel/event/mod.rs
new file mode 100644
index 0000000..6aea10c
--- /dev/null
+++ b/lib/channel/event/mod.rs
@@ -0,0 +1,114 @@
+pub mod ai;
+pub mod attachment;
+pub mod ban;
+pub mod category;
+pub mod common;
+pub mod conversation;
+pub mod dm;
+pub mod draft;
+pub mod forward;
+pub mod invite;
+pub mod member;
+pub mod message;
+pub mod message_read;
+pub mod notify;
+pub mod pin;
+pub mod presence;
+pub mod reaction;
+pub mod rooms;
+pub mod search;
+pub mod star;
+pub mod thread;
+pub mod voice;
+pub mod workspace;
+
+pub use common::{AgentInfo, RoomInfo, UserInfo, WorkspaceInfo};
+
+use model::room::RoomMessageModel;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use uuid::Uuid;
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum ChannelEventType {
+    MessageCreated,
+    MessageUpdated,
+    MessageDeleted,
+    ReactionCreated,
+    ReactionDeleted,
+    MessageRead,
+    DmCreated,
+    DmClosed,
+    ConversationUpdated,
+    Custom(String),
+}
+
+impl ChannelEventType {
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::MessageCreated => "message.created",
+            Self::MessageUpdated => "message.updated",
+            Self::MessageDeleted => "message.deleted",
+            Self::ReactionCreated => "reaction.created",
+            Self::ReactionDeleted => "reaction.deleted",
+            Self::MessageRead => "message.read",
+            Self::DmCreated => "dm.created",
+            Self::DmClosed => "dm.closed",
+            Self::ConversationUpdated => "conversation.updated",
+            Self::Custom(value) => value,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ChannelEvent {
+    pub room: Uuid,
+    pub seq: Option<i64>,
+    pub event_type: String,
+    pub message: Option<RoomMessageModel>,
+    pub payload: Option<Value>,
+    #[serde(default)]
+    pub sender_user: Option<UserInfo>,
+}
+
+impl ChannelEvent {
+    pub fn message_created(message: RoomMessageModel) -> Self {
+        Self {
+            room: message.room,
+            seq: Some(message.seq),
+            event_type: ChannelEventType::MessageCreated.as_str().to_owned(),
+            message: Some(message),
+            payload: None,
+            sender_user: None,
+        }
+    }
+
+    pub fn message_created_with_sender(
+        message: RoomMessageModel,
+        sender: UserInfo,
+    ) -> Self {
+        Self {
+            room: message.room,
+            seq: Some(message.seq),
+            event_type: ChannelEventType::MessageCreated.as_str().to_owned(),
+            message: Some(message),
+            payload: None,
+            sender_user: Some(sender),
+        }
+    }
+
+    pub fn custom(
+        room: Uuid,
+        event_type: impl Into<String>,
+        payload: Value,
+    ) -> Self {
+        Self {
+            room,
+            seq: None,
+            event_type: event_type.into(),
+            message: None,
+            payload: Some(payload),
+            sender_user: None,
+        }
+    }
+}
diff --git a/lib/channel/event/notify.rs b/lib/channel/event/notify.rs
new file mode 100644
index 0000000..fad42e1
--- /dev/null
+++ b/lib/channel/event/notify.rs
@@ -0,0 +1,69 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum NotifyEventType {
+    Created,
+    Read,
+    Archived,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum NotifyEvent {
+    #[serde(rename = "notify.created")]
+    Created(NotifyCreatedService),
+    #[serde(rename = "notify.read")]
+    Read(NotifyReadService),
+    #[serde(rename = "notify.archived")]
+    Archived(NotifyArchivedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NotifyCreatedService {
+    pub id: Uuid,
+    pub room: Option<RoomInfo>,
+    pub workspace: Option<WorkspaceInfo>,
+    pub user: UserInfo,
+    pub notification_type: String,
+    pub title: String,
+    pub content: Option<String>,
+    pub related_message_id: Option<Uuid>,
+    pub related_user: Option<UserInfo>,
+    pub metadata: Option<serde_json::Value>,
+    pub created_at: DateTime<Utc>,
+    pub deep_link_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NotifyReadService {
+    pub id: Uuid,
+    pub user: UserInfo,
+    pub read_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NotifyArchivedService {
+    pub id: Uuid,
+    pub user: UserInfo,
+    pub archived_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NotifyReadClient {
+    pub id: Uuid,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NotifyReadAllClient {
+    pub workspace: Option<WorkspaceInfo>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct NotifyArchiveClient {
+    pub id: Uuid,
+}
diff --git a/lib/channel/event/pin.rs b/lib/channel/event/pin.rs
new file mode 100644
index 0000000..dcf3c0d
--- /dev/null
+++ b/lib/channel/event/pin.rs
@@ -0,0 +1,49 @@
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+use serde::{Deserialize, Serialize};
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PinEventType {
+    Added,
+    Removed,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum PinEvent {
+    #[serde(rename = "pin.added")]
+    Added(PinAddedService),
+    #[serde(rename = "pin.removed")]
+    Removed(PinRemovedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PinAddedService {
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub pinned_by: UserInfo,
+    pub pinned_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PinRemovedService {
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub removed_by: UserInfo,
+    pub removed_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PinAddClient {
+    pub room: RoomInfo,
+    pub message: Uuid,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PinRemoveClient {
+    pub room: RoomInfo,
+    pub message: Uuid,
+}
diff --git a/lib/channel/event/presence.rs b/lib/channel/event/presence.rs
new file mode 100644
index 0000000..d44a03c
--- /dev/null
+++ b/lib/channel/event/presence.rs
@@ -0,0 +1,58 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::event::{UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PresenceEventType {
+    Changed,
+    CustomStatusUpdated,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum UserPresenceStatus {
+    Online,
+    Idle,
+    Dnd,
+    Offline,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum PresenceEvent {
+    #[serde(rename = "presence.changed")]
+    Changed(PresenceChangedService),
+    #[serde(rename = "presence.custom_status_updated")]
+    CustomStatusUpdated(CustomStatusUpdatedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PresenceChangedService {
+    pub user: UserInfo,
+    #[serde(rename = "workspace")]
+    pub project: Option<WorkspaceInfo>,
+    pub status: UserPresenceStatus,
+    pub last_seen_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CustomStatusUpdatedService {
+    pub user: UserInfo,
+    pub emoji: Option<String>,
+    pub text: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PresenceUpdateClient {
+    pub status: UserPresenceStatus,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CustomStatusUpdateClient {
+    pub emoji: Option<String>,
+    pub text: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/channel/event/reaction.rs b/lib/channel/event/reaction.rs
new file mode 100644
index 0000000..a618777
--- /dev/null
+++ b/lib/channel/event/reaction.rs
@@ -0,0 +1,73 @@
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+use serde::{Deserialize, Serialize};
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ReactionEventType {
+    Added,
+    Removed,
+    BatchUpdated,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum ReactionEvent {
+    #[serde(rename = "reaction.added")]
+    Added(ReactionAddedService),
+    #[serde(rename = "reaction.removed")]
+    Removed(ReactionRemovedService),
+    #[serde(rename = "reaction.batch_updated")]
+    BatchUpdated(ReactionBatchUpdatedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReactionAddedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub user: UserInfo,
+    pub emoji: String,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReactionRemovedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub user: UserInfo,
+    pub emoji: String,
+    pub removed_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReactionBatchUpdatedService {
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub reactions: Vec<ReactionGroup>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReactionGroup {
+    pub emoji: String,
+    pub count: i64,
+    pub reacted_by_me: bool,
+    pub users: Vec<UserInfo>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReactionAddClient {
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub emoji: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReactionRemoveClient {
+    pub room: RoomInfo,
+    pub message: Uuid,
+    pub emoji: String,
+}
diff --git a/lib/channel/event/rooms.rs b/lib/channel/event/rooms.rs
new file mode 100644
index 0000000..34b5cbf
--- /dev/null
+++ b/lib/channel/event/rooms.rs
@@ -0,0 +1,134 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RoomEventType {
+    Created,
+    Deleted,
+    Renamed,
+    TopicUpdated,
+    SettingsUpdated,
+    Moved,
+    AiUpdated,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum RoomEvent {
+    #[serde(rename = "room.created")]
+    Created(RoomCreatedService),
+    #[serde(rename = "room.deleted")]
+    Deleted(RoomDeletedService),
+    #[serde(rename = "room.renamed")]
+    Renamed(RoomRenamedService),
+    #[serde(rename = "room.moved")]
+    Moved(RoomMovedService),
+    #[serde(rename = "room.ai_updated")]
+    AiUpdated(RoomAiUpdatedService),
+    #[serde(rename = "room.topic_updated")]
+    TopicUpdated(RoomTopicUpdatedService),
+    #[serde(rename = "room.settings_updated")]
+    SettingsUpdated(RoomSettingsUpdatedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomCreatedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub public: bool,
+    pub category: Option<Uuid>,
+    pub created_by: UserInfo,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomDeletedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub deleted_by: UserInfo,
+    pub deleted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomRenamedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub old_name: String,
+    pub new_name: String,
+    pub renamed_by: UserInfo,
+    pub renamed_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomMovedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub old_category: Option<Uuid>,
+    pub new_category: Option<Uuid>,
+    pub moved_by: UserInfo,
+    pub moved_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomAiUpdatedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub model: Uuid,
+    pub model_name: String,
+    pub version: i64,
+    pub agent_type: String,
+    pub updated_by: UserInfo,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomTopicUpdatedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub old_topic: Option<String>,
+    pub new_topic: Option<String>,
+    pub updated_by: UserInfo,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomSettingsUpdatedService {
+    pub room: RoomInfo,
+    pub workspace: WorkspaceInfo,
+    pub slowmode_seconds: Option<i32>,
+    pub nsfw: bool,
+    pub default_auto_archive_duration: Option<i32>,
+    pub updated_by: UserInfo,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomCreateClient {
+    pub workspace: WorkspaceInfo,
+    pub room_name: String,
+    pub public: bool,
+    pub category: Option<Uuid>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomUpdateClient {
+    pub room_name: Option<String>,
+    pub public: Option<bool>,
+    pub category: Option<Uuid>,
+    pub topic: Option<String>,
+    pub slowmode_seconds: Option<i32>,
+    pub nsfw: Option<bool>,
+    pub default_auto_archive_duration: Option<i32>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomDeleteClient {}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RoomLoadClient {
+    pub room: RoomInfo,
+}
diff --git a/lib/channel/event/search.rs b/lib/channel/event/search.rs
new file mode 100644
index 0000000..3240117
--- /dev/null
+++ b/lib/channel/event/search.rs
@@ -0,0 +1,33 @@
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+use serde::{Deserialize, Serialize};
+
+use crate::event::{RoomInfo, UserInfo, message::MessageNewService};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SearchResultService {
+    pub q: String,
+    pub room: Option<RoomInfo>,
+    pub messages: Vec<SearchMessageHitService>,
+    pub total: i64,
+    pub took_ms: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SearchMessageHitService {
+    #[serde(flatten)]
+    pub message: MessageNewService,
+    pub highlighted_content: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SearchClient {
+    pub q: String,
+    pub room: Option<Uuid>,
+    pub start_time: Option<DateTime<Utc>>,
+    pub end_time: Option<DateTime<Utc>>,
+    pub sender: Option<UserInfo>,
+    pub content_type: Option<String>,
+    pub limit: Option<u64>,
+    pub offset: Option<u64>,
+}
diff --git a/lib/channel/event/star.rs b/lib/channel/event/star.rs
new file mode 100644
index 0000000..8bda44b
--- /dev/null
+++ b/lib/channel/event/star.rs
@@ -0,0 +1,47 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageStarredService {
+    pub room: RoomInfo,
+    pub message_id: Uuid,
+    pub message_seq: i64,
+    pub starred_by: UserInfo,
+    pub starred_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageUnstarredService {
+    pub room: RoomInfo,
+    pub message_id: Uuid,
+    pub unstarred_by: UserInfo,
+    pub unstarred_at: DateTime<Utc>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StarredMessageEntry {
+    pub message_id: Uuid,
+    pub room: RoomInfo,
+    pub seq: i64,
+    pub content: String,
+    pub content_type: String,
+    pub sender: UserInfo,
+    pub starred_at: DateTime<Utc>,
+    pub sent_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageStarClient {
+    pub room: Uuid,
+    pub message_id: Uuid,
+    pub star: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StarredListClient {
+    pub room: Option<Uuid>,
+    pub limit: Option<u64>,
+    pub offset: Option<u64>,
+}
diff --git a/lib/channel/event/thread.rs b/lib/channel/event/thread.rs
new file mode 100644
index 0000000..3d373fc
--- /dev/null
+++ b/lib/channel/event/thread.rs
@@ -0,0 +1,105 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ThreadEventType {
+    Created,
+    Updated,
+    Resolved,
+    Archived,
+    ParticipantJoined,
+    ParticipantLeft,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum ThreadEvent {
+    #[serde(rename = "thread.created")]
+    Created(ThreadCreatedService),
+    #[serde(rename = "thread.updated")]
+    Updated(ThreadUpdatedService),
+    #[serde(rename = "thread.resolved")]
+    Resolved(ThreadResolvedService),
+    #[serde(rename = "thread.archived")]
+    Archived(ThreadArchivedService),
+    #[serde(rename = "thread.participant_joined")]
+    ParticipantJoined(ThreadParticipantJoinedService),
+    #[serde(rename = "thread.participant_left")]
+    ParticipantLeft(ThreadParticipantLeftService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadCreatedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub parent: i64,
+    pub created_by: UserInfo,
+    pub participants: serde_json::Value,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadUpdatedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub last_message_at: Option<DateTime<Utc>>,
+    pub last_message_preview: Option<String>,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadResolvedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub resolved_by: UserInfo,
+    pub resolved_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadArchivedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub archived_by: UserInfo,
+    pub archived_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadParticipantJoinedService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub joined_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadParticipantLeftService {
+    pub id: Uuid,
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub left_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadCreateClient {
+    pub room: RoomInfo,
+    pub parent_seq: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadResolveClient {
+    pub thread_id: Uuid,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadArchiveClient {
+    pub thread_id: Uuid,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ThreadLoadClient {
+    pub thread_id: Uuid,
+}
diff --git a/lib/channel/event/voice.rs b/lib/channel/event/voice.rs
new file mode 100644
index 0000000..1fd15f9
--- /dev/null
+++ b/lib/channel/event/voice.rs
@@ -0,0 +1,125 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum VoiceEventType {
+    ChannelJoined,
+    ChannelLeft,
+    MuteUpdated,
+    DeafUpdated,
+    ScreenShareStarted,
+    ScreenShareStopped,
+    SpeakingStarted,
+    SpeakingStopped,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum VoiceEvent {
+    #[serde(rename = "voice.channel_joined")]
+    ChannelJoined(VoiceChannelJoinedService),
+    #[serde(rename = "voice.channel_left")]
+    ChannelLeft(VoiceChannelLeftService),
+    #[serde(rename = "voice.mute_updated")]
+    MuteUpdated(VoiceMuteUpdatedService),
+    #[serde(rename = "voice.deaf_updated")]
+    DeafUpdated(VoiceDeafUpdatedService),
+    #[serde(rename = "voice.screen_share_started")]
+    ScreenShareStarted(ScreenShareStartedService),
+    #[serde(rename = "voice.screen_share_stopped")]
+    ScreenShareStopped(ScreenShareStoppedService),
+    #[serde(rename = "voice.speaking_started")]
+    SpeakingStarted(SpeakingStartedService),
+    #[serde(rename = "voice.speaking_stopped")]
+    SpeakingStopped(SpeakingStoppedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceChannelJoinedService {
+    pub room: RoomInfo,
+    pub workspace: Option<WorkspaceInfo>,
+    pub user: UserInfo,
+    pub muted: bool,
+    pub deafened: bool,
+    pub video: bool,
+    pub joined_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceChannelLeftService {
+    pub room: RoomInfo,
+    pub workspace: Option<WorkspaceInfo>,
+    pub user: UserInfo,
+    pub left_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceMuteUpdatedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub muted: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceDeafUpdatedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub deafened: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ScreenShareStartedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub started_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ScreenShareStoppedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+    pub stopped_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SpeakingStartedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SpeakingStoppedService {
+    pub room: RoomInfo,
+    pub user: UserInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceJoinClient {
+    pub room: RoomInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceLeaveClient {
+    pub room: RoomInfo,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceMuteClient {
+    pub room: RoomInfo,
+    pub muted: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct VoiceDeafClient {
+    pub room: RoomInfo,
+    pub deafened: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ScreenShareClient {
+    pub room: RoomInfo,
+    pub start: bool,
+}
diff --git a/lib/channel/event/workspace.rs b/lib/channel/event/workspace.rs
new file mode 100644
index 0000000..1eabbe9
--- /dev/null
+++ b/lib/channel/event/workspace.rs
@@ -0,0 +1,120 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum WorkspaceEventType {
+    RoomCreated,
+    RoomDeleted,
+    RoomRenamed,
+    RoomMoved,
+    RepoCreated,
+    RepoUpdated,
+    RepoDeleted,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum WorkspaceEvent {
+    #[serde(rename = "workspace.room_created")]
+    RoomCreated(WorkspaceRoomCreatedService),
+    #[serde(rename = "workspace.room_deleted")]
+    RoomDeleted(WorkspaceRoomDeletedService),
+    #[serde(rename = "workspace.room_renamed")]
+    RoomRenamed(WorkspaceRoomRenamedService),
+    #[serde(rename = "workspace.room_moved")]
+    RoomMoved(WorkspaceRoomMovedService),
+    #[serde(rename = "workspace.repo_created")]
+    RepoCreated(WorkspaceRepoCreatedService),
+    #[serde(rename = "workspace.repo_updated")]
+    RepoUpdated(WorkspaceRepoUpdatedService),
+    #[serde(rename = "workspace.repo_deleted")]
+    RepoDeleted(WorkspaceRepoDeletedService),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomCreatedService {
+    pub workspace: WorkspaceInfo,
+    pub room: RoomInfo,
+    pub public: bool,
+    pub category: Option<Uuid>,
+    pub created_by: UserInfo,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomDeletedService {
+    pub workspace: WorkspaceInfo,
+    pub room: RoomInfo,
+    pub deleted_by: UserInfo,
+    pub deleted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomRenamedService {
+    pub workspace: WorkspaceInfo,
+    pub room: RoomInfo,
+    pub old_name: String,
+    pub new_name: String,
+    pub renamed_by: UserInfo,
+    pub renamed_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomMovedService {
+    pub workspace: WorkspaceInfo,
+    pub room: RoomInfo,
+    pub old_category: Option<Uuid>,
+    pub new_category: Option<Uuid>,
+    pub moved_by: UserInfo,
+    pub moved_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRepoCreatedService {
+    pub workspace: WorkspaceInfo,
+    pub repo: Uuid,
+    pub repo_name: String,
+    pub created_by: UserInfo,
+    pub created_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRepoUpdatedService {
+    pub workspace: WorkspaceInfo,
+    pub repo: Uuid,
+    pub updated_by: UserInfo,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRepoDeletedService {
+    pub workspace: WorkspaceInfo,
+    pub repo: Uuid,
+    pub deleted_by: UserInfo,
+    pub deleted_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomCreateClient {
+    pub workspace: Uuid,
+    pub room_name: String,
+    pub public: bool,
+    pub category: Option<Uuid>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomUpdateClient {
+    pub room: Uuid,
+    pub room_name: Option<String>,
+    pub public: Option<bool>,
+    pub category: Option<Uuid>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkspaceRoomDeleteClient {
+    pub room: Uuid,
+}
diff --git a/lib/channel/http/dispatch.rs b/lib/channel/http/dispatch.rs
new file mode 100644
index 0000000..714ed56
--- /dev/null
+++ b/lib/channel/http/dispatch.rs
@@ -0,0 +1,114 @@
+use uuid::Uuid;
+
+use crate::event::{member, message, notify, reaction};
+use crate::event::{RoomInfo, UserInfo};
+
+use super::out_event::WsOutEvent;
+
+pub struct EventDispatcher;
+
+impl EventDispatcher {
+    pub fn dispatch_message(
+        room_id: Uuid,
+        room_name: &str,
+        msg: &model::room::RoomMessageModel,
+    ) -> WsOutEvent {
+        let room = RoomInfo {
+            id: room_id,
+            name: room_name.to_string(),
+        };
+        WsOutEvent::MessageNew {
+            room: room.clone(),
+            data: message::MessageNewService {
+                id: msg.id,
+                seq: msg.seq,
+                room,
+                sender_type: "user".to_string(),
+                sender: UserInfo::unknown(msg.author),
+                thread: msg.thread,
+                in_reply_to: msg.parent,
+                content: msg.content.clone(),
+                content_type: msg.content_type.clone(),
+                pinned: msg.pinned,
+                system_type: msg.system_type.clone(),
+                metadata: msg.metadata.clone(),
+                thinking_content: None,
+                thinking_is_chunked: None,
+                send_at: msg.created_at,
+                reactions: vec![],
+            },
+        }
+    }
+
+    pub fn dispatch_typing_start(
+        room_id: Uuid,
+        _room_name: &str,
+        user_id: Uuid,
+        display_name: Option<String>,
+    ) -> WsOutEvent {
+        let user = UserInfo {
+            id: user_id,
+            username: display_name.clone().unwrap_or_default(),
+            display_name: display_name.unwrap_or_default(),
+            avatar_url: String::new(),
+        };
+        let room = RoomInfo::unknown(room_id);
+        WsOutEvent::TypingStart {
+            room: room.clone(),
+            data: member::TypingStartService {
+                room,
+                user,
+                sender_type: "user".to_string(),
+            },
+        }
+    }
+
+    pub fn dispatch_typing_stop(
+        room_id: Uuid,
+        _room_name: &str,
+        user_id: Uuid,
+        display_name: Option<String>,
+    ) -> WsOutEvent {
+        let user = UserInfo {
+            id: user_id,
+            username: display_name.clone().unwrap_or_default(),
+            display_name: display_name.unwrap_or_default(),
+            avatar_url: String::new(),
+        };
+        let room = RoomInfo::unknown(room_id);
+        WsOutEvent::TypingStop {
+            room: room.clone(),
+            data: member::TypingStopService {
+                room,
+                user,
+                sender_type: "user".to_string(),
+            },
+        }
+    }
+
+    pub fn dispatch_reactions(
+        room_id: Uuid,
+        room_name: &str,
+        message_id: Uuid,
+        groups: Vec<reaction::ReactionGroup>,
+    ) -> WsOutEvent {
+        let room = RoomInfo {
+            id: room_id,
+            name: room_name.to_string(),
+        };
+        WsOutEvent::ReactionBatchUpdated {
+            room: room.clone(),
+            data: reaction::ReactionBatchUpdatedService {
+                room,
+                message: message_id,
+                reactions: groups,
+            },
+        }
+    }
+
+    pub fn dispatch_notification(
+        data: notify::NotifyCreatedService,
+    ) -> WsOutEvent {
+        WsOutEvent::NotifyCreated { data }
+    }
+}
diff --git a/lib/channel/http/handler/ai.rs b/lib/channel/http/handler/ai.rs
new file mode 100644
index 0000000..1e0be2e
--- /dev/null
+++ b/lib/channel/http/handler/ai.rs
@@ -0,0 +1,159 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{AgentInfo, RoomInfo, ai};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn ai_list(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let rows = db::sqlx::query_as::<_, (Uuid, Option<String>, Option<String>, Option<Uuid>, bool, bool)>(
+            "SELECT ra.agent_session, s.name, s.agent_kind, s.model_version, ra.enabled, ra.auto_reply \
+             FROM room_ai ra \
+             LEFT JOIN agent_session s ON s.id = ra.agent_session AND s.deleted_at IS NULL \
+             WHERE ra.room = $1",
+        )
+        .bind(room)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+
+        let agents = rows
+            .into_iter()
+            .filter_map(|(agent_session, name, agent_kind, model_version, enabled, auto_reply)| {
+                name.map(|n| ai::RoomAiEntry {
+                    agent_session,
+                    name: n,
+                    agent_kind: agent_kind.unwrap_or_default(),
+                    model_version,
+                    enabled,
+                    auto_reply,
+                })
+            })
+            .collect();
+
+        let ai_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        Ok(Some(WsOutEvent::AiAgentList {
+            room: ai_room.clone(),
+            data: ai::RoomAiListService {
+                room: ai_room,
+                agents,
+            },
+        }))
+    }
+
+    pub(super) async fn ai_upsert(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        model: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let session = db::sqlx::query_as::<_, model::agent::AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, enabled, created_by, \
+             created_at, updated_at, deleted_at \
+             FROM agent_session WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(model)
+        .fetch_one(bus.inner.db.reader())
+        .await
+        .map_err(|e| match e {
+            db::sqlx::Error::RowNotFound => ChannelError::RoomNotFound,
+            other => ChannelError::Database(other),
+        })?;
+        db::sqlx::query_as::<_, model::room::RoomAiModel>(
+            "INSERT INTO room_ai (room, agent_session, enabled, auto_reply, created_by, created_at, updated_at) \
+             VALUES ($1, $2, true, false, $3, now(), now()) \
+             ON CONFLICT (room, agent_session) DO UPDATE SET enabled = true, updated_at = now() \
+             RETURNING room, agent_session, enabled, auto_reply, created_by, created_at, updated_at",
+        )
+        .bind(room)
+        .bind(model)
+        .bind(user_id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let ai_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let data = ai::AiAgentJoinedService {
+            room: ai_room,
+            agent: AgentInfo {
+                id: model,
+                name: session.name.clone(),
+                agent_type: session.agent_kind.clone(),
+                model_name: None,
+            },
+            joined_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "ai.agent_joined", &data)
+            .await?;
+
+        Ok(Some(WsOutEvent::AiAgentJoined { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn ai_delete(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        agent_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let session = db::sqlx::query_as::<_, model::agent::AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, enabled, created_by, \
+             created_at, updated_at, deleted_at \
+             FROM agent_session WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(agent_id)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+
+        let result = db::sqlx::query(
+            "DELETE FROM room_ai WHERE room = $1 AND agent_session = $2",
+        )
+        .bind(room)
+        .bind(agent_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+
+        if result.rows_affected() == 0 {
+            return Err(ChannelError::RoomNotFound);
+        }
+        let ai_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let agent_info = session.map(|s| AgentInfo {
+            id: s.id,
+            name: s.name,
+            agent_type: s.agent_kind,
+            model_name: None,
+        }).unwrap_or_else(|| AgentInfo::unknown(agent_id));
+
+        let data = ai::AiAgentLeftService {
+            room: ai_room,
+            agent: agent_info,
+            left_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "ai.agent_left", &data).await?;
+
+        Ok(Some(WsOutEvent::AiAgentLeft { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn ai_stop(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        bus.publish_room_event(
+            room,
+            "ai.stop",
+            &serde_json::json!({"stopped_by": user_id}),
+        )
+        .await?;
+        Ok(None)
+    }
+}
diff --git a/lib/channel/http/handler/ban.rs b/lib/channel/http/handler/ban.rs
new file mode 100644
index 0000000..1fe8760
--- /dev/null
+++ b/lib/channel/http/handler/ban.rs
@@ -0,0 +1,74 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{UserInfo, WorkspaceInfo, ban};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn ban_create(
+        bus: &ChannelBus,
+        _user_id: Uuid,
+        workspace: Uuid,
+        user: Uuid,
+        reason: Option<String>,
+        _expires_at: Option<chrono::DateTime<chrono::Utc>>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_workspace_member(bus, _user_id, workspace).await?;
+        db::sqlx::query(
+            "INSERT INTO user_blacklist (\"user\", black, created_at) \
+             VALUES ($1, $2, now()) \
+             ON CONFLICT DO NOTHING",
+        )
+        .bind(user)
+        .bind(_user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let ban_key = format!("ban:{}:{}:{}", workspace, _user_id, user);
+        let ban_data = serde_json::json!({
+            "workspace": workspace,
+            "banned_by": _user_id,
+            "reason": reason,
+            "expires_at": _expires_at,
+            "banned_at": Utc::now(),
+        });
+        bus.inner.cache.set(&ban_key, &ban_data).await?;
+        let data = ban::BannedService {
+            workspace: bus.lookup_workspace(workspace).await.unwrap_or_else(|_| WorkspaceInfo::unknown(workspace)),
+            user: bus.lookup_user(user).await.unwrap_or_else(|_| UserInfo::unknown(user)),
+            banned_by: bus.lookup_user(_user_id).await.unwrap_or_else(|_| UserInfo::unknown(_user_id)),
+            reason,
+            expires_at: _expires_at,
+            banned_at: Utc::now(),
+        };
+        bus.workspace_changed(workspace).await?;
+        Ok(Some(WsOutEvent::UserBanned { data }))
+    }
+
+    pub(super) async fn ban_remove(
+        bus: &ChannelBus,
+        _user_id: Uuid,
+        workspace: Uuid,
+        user: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        db::sqlx::query(
+            "DELETE FROM user_blacklist WHERE \"user\" = $1 AND black = $2",
+        )
+        .bind(user)
+        .bind(_user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let ban_key = format!("ban:{}:{}:{}", workspace, _user_id, user);
+        bus.inner.cache.remove(&ban_key).await?;
+        let data = ban::UnbannedService {
+            workspace: bus.lookup_workspace(workspace).await.unwrap_or_else(|_| WorkspaceInfo::unknown(workspace)),
+            user: bus.lookup_user(user).await.unwrap_or_else(|_| UserInfo::unknown(user)),
+            unbanned_by: bus.lookup_user(_user_id).await.unwrap_or_else(|_| UserInfo::unknown(_user_id)),
+            unbanned_at: Utc::now(),
+        };
+        bus.workspace_changed(workspace).await?;
+        Ok(Some(WsOutEvent::UserUnbanned { data }))
+    }
+}
diff --git a/lib/channel/http/handler/category.rs b/lib/channel/http/handler/category.rs
new file mode 100644
index 0000000..017609f
--- /dev/null
+++ b/lib/channel/http/handler/category.rs
@@ -0,0 +1,138 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{UserInfo, WorkspaceInfo, category};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::MAX_CATEGORY_NAME_LEN;
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn category_create(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        workspace: Uuid,
+        name: String,
+        position: Option<i32>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        if name.is_empty() || name.len() > MAX_CATEGORY_NAME_LEN {
+            return Err(ChannelError::Validation("invalid category name".into()));
+        }
+        Self::ensure_workspace_member(bus, user_id, workspace).await?;
+        let row = db::sqlx::query_as::<_, model::room::RoomCategoryModel>(
+            "INSERT INTO room_category (wk, name, position, created_at, updated_at) \
+             VALUES ($1, $2, $3, now(), now()) \
+             RETURNING id, wk, name, position, collapsed, created_at, updated_at",
+        )
+        .bind(workspace)
+        .bind(&name)
+        .bind(position.unwrap_or(0))
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let cc_workspace = bus
+            .lookup_workspace(workspace)
+            .await
+            .unwrap_or_else(|_| WorkspaceInfo::unknown(workspace));
+        let cc_user = bus
+            .lookup_user(user_id)
+            .await
+            .unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = category::CategoryCreatedService {
+            id: row.id,
+            project: cc_workspace,
+            name: row.name,
+            position: row.position,
+            created_by: cc_user,
+            created_at: row.created_at,
+        };
+        bus.workspace_changed(workspace).await?;
+        Ok(Some(WsOutEvent::CategoryCreated {
+            workspace: data.project.clone(),
+            data,
+        }))
+    }
+
+    pub(super) async fn category_update(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        id: Uuid,
+        name: Option<String>,
+        position: Option<i32>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let old = db::sqlx::query_as::<_, model::room::RoomCategoryModel>(
+            "SELECT id, wk, name, position, collapsed, created_at, updated_at \
+             FROM room_category WHERE id = $1",
+        )
+        .bind(id)
+        .fetch_one(bus.inner.db.reader())
+        .await?;
+        Self::ensure_workspace_member(bus, user_id, old.wk).await?;
+        let new_name = name.unwrap_or(old.name.clone());
+        let new_position = position.unwrap_or(old.position);
+        db::sqlx::query(
+            "UPDATE room_category SET name = $2, position = $3, updated_at = now() WHERE id = $1",
+        )
+        .bind(id)
+        .bind(&new_name)
+        .bind(new_position)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let cu_workspace = bus
+            .lookup_workspace(old.wk)
+            .await
+            .unwrap_or_else(|_| WorkspaceInfo::unknown(old.wk));
+        let cu_user = bus
+            .lookup_user(user_id)
+            .await
+            .unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = category::CategoryUpdatedService {
+            id,
+            project: cu_workspace,
+            name: Some(new_name),
+            position: Some(new_position),
+            updated_by: cu_user,
+            updated_at: Utc::now(),
+        };
+        bus.workspace_changed(old.wk).await?;
+        Ok(Some(WsOutEvent::CategoryUpdated { workspace: data.project.clone(), data }))
+    }
+
+    pub(super) async fn category_delete(
+        bus: &ChannelBus,
+        _user_id: Uuid,
+        id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let existing = db::sqlx::query_as::<_, model::room::RoomCategoryModel>(
+            "SELECT id, wk, name, position, collapsed, created_at, updated_at \
+             FROM room_category WHERE id = $1",
+        )
+        .bind(id)
+        .fetch_one(bus.inner.db.reader())
+        .await?;
+        Self::ensure_workspace_member(bus, _user_id, existing.wk).await?;
+        let row = db::sqlx::query_as::<_, model::room::RoomCategoryModel>(
+            "DELETE FROM room_category WHERE id = $1 \
+             RETURNING id, wk, name, position, collapsed, created_at, updated_at",
+        )
+        .bind(id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let cd_workspace = bus
+            .lookup_workspace(row.wk)
+            .await
+            .unwrap_or_else(|_| WorkspaceInfo::unknown(row.wk));
+        let cd_user = bus
+            .lookup_user(_user_id)
+            .await
+            .unwrap_or_else(|_| UserInfo::unknown(_user_id));
+        let data = category::CategoryDeletedService {
+            id: row.id,
+            project: cd_workspace.clone(),
+            deleted_by: cd_user,
+            deleted_at: Utc::now(),
+        };
+        bus.workspace_changed(row.wk).await?;
+        Ok(Some(WsOutEvent::CategoryDeleted { workspace: cd_workspace, data }))
+    }
+}
diff --git a/lib/channel/http/handler/conversation.rs b/lib/channel/http/handler/conversation.rs
new file mode 100644
index 0000000..47ce248
--- /dev/null
+++ b/lib/channel/http/handler/conversation.rs
@@ -0,0 +1,231 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, conversation};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn conversation_pin(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        pin: bool,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let now = Utc::now();
+        db::sqlx::query(
+            "INSERT INTO user_room_state (\"user\", room, is_pinned, updated_at) \
+             VALUES ($1, $2, $3, $4) \
+             ON CONFLICT (\"user\", room) DO UPDATE \
+             SET is_pinned = $3, updated_at = $4",
+        )
+        .bind(user_id)
+        .bind(room)
+        .bind(pin)
+        .bind(now)
+        .execute(bus.inner.db.writer())
+        .await?;
+
+        let room_info =
+            bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let user_info =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+        if pin {
+            let data = conversation::ConversationPinnedService {
+                user: user_info,
+                room: room_info.clone(),
+                pinned_at: now,
+            };
+            bus.emit_to_user(user_id, "conversation.pinned", &data).await?;
+            Ok(Some(WsOutEvent::ConversationPinned {
+                room: room_info,
+                data,
+            }))
+        } else {
+            let data = conversation::ConversationUnpinnedService {
+                user: user_info,
+                room: room_info.clone(),
+                unpinned_at: now,
+            };
+            bus.emit_to_user(user_id, "conversation.unpinned", &data).await?;
+            Ok(Some(WsOutEvent::ConversationUnpinned {
+                room: room_info,
+                data,
+            }))
+        }
+    }
+    pub(super) async fn conversation_mute(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        mute: bool,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let now = Utc::now();
+
+        db::sqlx::query(
+            "INSERT INTO user_room_state (\"user\", room, is_muted, updated_at) \
+             VALUES ($1, $2, $3, $4) \
+             ON CONFLICT (\"user\", room) DO UPDATE \
+             SET is_muted = $3, updated_at = $4",
+        )
+        .bind(user_id)
+        .bind(room)
+        .bind(mute)
+        .bind(now)
+        .execute(bus.inner.db.writer())
+        .await?;
+
+        let room_info =
+            bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let user_info =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+        if mute {
+            let data = conversation::ConversationMutedService {
+                user: user_info,
+                room: room_info.clone(),
+                muted_at: now,
+            };
+            bus.emit_to_user(user_id, "conversation.muted", &data).await?;
+            Ok(Some(WsOutEvent::ConversationMuted {
+                room: room_info,
+                data,
+            }))
+        } else {
+            let data = conversation::ConversationUnmutedService {
+                user: user_info,
+                room: room_info.clone(),
+                unmuted_at: now,
+            };
+            bus.emit_to_user(user_id, "conversation.unmuted", &data).await?;
+            Ok(Some(WsOutEvent::ConversationUnmuted {
+                room: room_info,
+                data,
+            }))
+        }
+    }
+    pub(super) async fn conversation_notify_level(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        notify_level: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let valid = matches!(notify_level.as_str(), "all" | "mentions" | "none");
+        if !valid {
+            return Err(crate::ChannelError::Internal(
+                "notify_level must be 'all', 'mentions', or 'none'".to_string(),
+            ));
+        }
+
+        let now = Utc::now();
+        let old_level: Option<(String,)> = db::sqlx::query_as(
+            "SELECT notify_level FROM user_room_state \
+             WHERE \"user\" = $1 AND room = $2",
+        )
+        .bind(user_id)
+        .bind(room)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        let old = old_level.map(|r| r.0).unwrap_or_else(|| "all".to_string());
+
+        db::sqlx::query(
+            "INSERT INTO user_room_state (\"user\", room, notify_level, updated_at) \
+             VALUES ($1, $2, $3, $4) \
+             ON CONFLICT (\"user\", room) DO UPDATE \
+             SET notify_level = $3, updated_at = $4",
+        )
+        .bind(user_id)
+        .bind(room)
+        .bind(&notify_level)
+        .bind(now)
+        .execute(bus.inner.db.writer())
+        .await?;
+
+        let room_info =
+            bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let user_info =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+        let data = conversation::ConversationNotifyLevelChangedService {
+            user: user_info,
+            room: room_info.clone(),
+            old_level: old,
+            new_level: notify_level,
+            updated_at: now,
+        };
+        bus.emit_to_user(user_id, "conversation.notify_level_changed", &data)
+            .await?;
+        Ok(None)
+    }
+    pub(super) async fn conversation_list(
+        bus: &ChannelBus,
+        user_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let rooms = crate::rooms::user_rooms(
+            &bus.inner.db,
+            &bus.inner.cache,
+            &bus.inner.config,
+            user_id,
+        )
+        .await?;
+
+        if rooms.is_empty() {
+            return Ok(Some(WsOutEvent::ConversationList { data: vec![] }));
+        }
+        let rows = db::sqlx::query_as::<_, (
+            Uuid,           // room id
+            String,         // room name
+            String,         // room type
+            bool,           // is_pinned
+            bool,           // is_muted
+            String,         // notify_level
+            i64,            // last_read_seq
+            i64,            // max seq from room_message
+        )>(
+            "SELECT r.id, r.name, r.room_type, \
+                    COALESCE(s.is_pinned, false), \
+                    COALESCE(s.is_muted, false), \
+                    COALESCE(s.notify_level, 'all'), \
+                    COALESCE(s.last_read_seq, 0), \
+                    COALESCE((SELECT MAX(seq) FROM room_message \
+                              WHERE room = r.id AND deleted_at IS NULL), 0) \
+             FROM room r \
+             LEFT JOIN user_room_state s ON s.room = r.id AND s.\"user\" = $1 \
+             WHERE r.id = ANY($2) AND r.deleted_at IS NULL AND r.is_archived = false \
+             ORDER BY COALESCE(s.is_pinned, false) DESC, r.name",
+        )
+        .bind(user_id)
+        .bind(&rooms)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+
+        let summaries: Vec<conversation::ConversationSummary> = rows
+            .into_iter()
+            .map(
+                |(id, name, room_type, is_pinned, is_muted, notify_level, last_read_seq, max_seq)| {
+                    let unread = (max_seq - last_read_seq).max(0);
+                    conversation::ConversationSummary {
+                        room: id,
+                        room_name: name,
+                        room_type,
+                        is_pinned,
+                        is_muted,
+                        notify_level,
+                        last_read_seq,
+                        max_seq,
+                        unread_count: unread,
+                        last_read_at: None,
+                    }
+                },
+            )
+            .collect();
+
+        Ok(Some(WsOutEvent::ConversationList { data: summaries }))
+    }
+}
diff --git a/lib/channel/http/handler/dm.rs b/lib/channel/http/handler/dm.rs
new file mode 100644
index 0000000..680a5ee
--- /dev/null
+++ b/lib/channel/http/handler/dm.rs
@@ -0,0 +1,248 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, dm};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn dm_create(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        recipient: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        if user_id == recipient {
+            return Err(crate::ChannelError::Internal(
+                "cannot create DM with yourself".to_string(),
+            ));
+        }
+        let recipient_exists: Option<(Uuid,)> = db::sqlx::query_as(
+            "SELECT id FROM \"user\" WHERE id = $1",
+        )
+        .bind(recipient)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        if recipient_exists.is_none() {
+            return Err(crate::ChannelError::UserNotFound);
+        }
+        let (initiator, other) = if user_id < recipient {
+            (user_id, recipient)
+        } else {
+            (recipient, user_id)
+        };
+        let existing: Option<(Uuid, Uuid, bool)> = db::sqlx::query_as(
+            "SELECT room, initiator, is_closed FROM dm_conversation \
+             WHERE initiator = $1 AND recipient = $2",
+        )
+        .bind(initiator)
+        .bind(other)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+
+        let now = Utc::now();
+
+        let (room_id, is_reopen) = if let Some((room, _, is_closed)) = existing {
+            if is_closed {
+                db::sqlx::query(
+                    "UPDATE dm_conversation SET is_closed = false, closed_at = NULL, \
+                     updated_at = now() WHERE initiator = $1 AND recipient = $2",
+                )
+                .bind(initiator)
+                .bind(other)
+                .execute(bus.inner.db.writer())
+                .await?;
+                db::sqlx::query(
+                    "UPDATE room SET is_archived = false, updated_at = now() WHERE id = $1",
+                )
+                .bind(room)
+                .execute(bus.inner.db.writer())
+                .await?;
+
+                (room, true)
+            } else {
+                (room, false)
+            }
+        } else {
+            let shared_wk: Option<(Uuid,)> = db::sqlx::query_as(
+                "SELECT wm1.wk FROM wk_member wm1 \
+                 INNER JOIN wk_member wm2 ON wm2.wk = wm1.wk \
+                 WHERE wm1.\"user\" = $1 AND wm1.leave_at IS NULL \
+                   AND wm2.\"user\" = $2 AND wm2.leave_at IS NULL \
+                 LIMIT 1",
+            )
+            .bind(user_id)
+            .bind(recipient)
+            .fetch_optional(bus.inner.db.reader())
+            .await?;
+
+            let wk = shared_wk.map(|r| r.0).unwrap_or_else(|| {
+                Uuid::nil()
+            });
+            let room_id = Uuid::new_v4();
+            db::sqlx::query(
+                "INSERT INTO room (id, wk, name, topic, room_type, position, is_private, \
+                 created_by, created_at, updated_at) \
+                 VALUES ($1, $2, $3, NULL, 'DM', 0, true, $4, now(), now())",
+            )
+            .bind(room_id)
+            .bind(wk)
+            .bind(format!("dm-{}", &room_id.to_string()[..8]))
+            .bind(user_id)
+            .execute(bus.inner.db.writer())
+            .await?;
+            db::sqlx::query(
+                "INSERT INTO dm_conversation (room, initiator, recipient, created_at, updated_at) \
+                 VALUES ($1, $2, $3, now(), now()) \
+                 ON CONFLICT (initiator, recipient) DO NOTHING",
+            )
+            .bind(room_id)
+            .bind(initiator)
+            .bind(other)
+            .execute(bus.inner.db.writer())
+            .await?;
+            for uid in &[user_id, recipient] {
+                db::sqlx::query(
+                    "INSERT INTO room_permission_overwrite \
+                     (room, target_type, target_id, allow_mask, deny_mask, created_at) \
+                     VALUES ($1, 'user', $2, 0, 0, now()) \
+                     ON CONFLICT DO NOTHING",
+                )
+                .bind(room_id)
+                .bind(uid)
+                .execute(bus.inner.db.writer())
+                .await?;
+            }
+
+            (room_id, false)
+        };
+        let _ = crate::rooms::refresh_user_rooms_cache(
+            &bus.inner.db,
+            &bus.inner.cache,
+            &bus.inner.config,
+            user_id,
+        )
+        .await;
+        let _ = crate::rooms::refresh_user_rooms_cache(
+            &bus.inner.db,
+            &bus.inner.cache,
+            &bus.inner.config,
+            recipient,
+        )
+        .await;
+
+        let room_info =
+            bus.lookup_room(room_id).await.unwrap_or_else(|_| RoomInfo::unknown(room_id));
+        let initiator_info =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let recipient_info =
+            bus.lookup_user(recipient).await.unwrap_or_else(|_| UserInfo::unknown(recipient));
+
+        if is_reopen {
+            let data = dm::DmReopenedService {
+                room: room_info.clone(),
+                reopened_by: initiator_info,
+                reopened_at: now,
+            };
+            bus.emit_to_user(user_id, "dm.reopened", &data).await?;
+            bus.emit_to_user(recipient, "dm.reopened", &data).await?;
+            Ok(Some(WsOutEvent::DmReopened {
+                room: room_info,
+                data,
+            }))
+        } else {
+            let data = dm::DmCreatedService {
+                room: room_info.clone(),
+                initiator: initiator_info,
+                recipient: recipient_info,
+                created_at: now,
+            };
+            bus.emit_to_user(user_id, "dm.created", &data).await?;
+            bus.emit_to_user(recipient, "dm.created", &data).await?;
+            Ok(Some(WsOutEvent::DmCreated {
+                room: room_info,
+                data,
+            }))
+        }
+    }
+    pub(super) async fn dm_close(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let now = Utc::now();
+
+        let result = db::sqlx::query(
+            "UPDATE dm_conversation SET is_closed = true, closed_at = $1, updated_at = $1 \
+             WHERE room = $2 AND (initiator = $3 OR recipient = $3) AND is_closed = false",
+        )
+        .bind(now)
+        .bind(room)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+
+        if result.rows_affected() == 0 {
+            return Ok(None);
+        }
+
+        let room_info =
+            bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let closed_by =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+        let data = dm::DmClosedService {
+            room: room_info.clone(),
+            closed_by,
+            closed_at: now,
+        };
+        bus.publish_room_event(room, "dm.closed", &data).await?;
+        Ok(Some(WsOutEvent::DmClosed {
+            room: room_info,
+            data,
+        }))
+    }
+    pub(super) async fn dm_list(
+        bus: &ChannelBus,
+        user_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let rows = db::sqlx::query_as::<_, (Uuid, Uuid, Uuid, chrono::DateTime<Utc>)>(
+            "SELECT dc.room, dc.initiator, dc.recipient, dc.created_at \
+             FROM dm_conversation dc \
+             INNER JOIN room r ON r.id = dc.room \
+             WHERE (dc.initiator = $1 OR dc.recipient = $1) \
+               AND dc.is_closed = false \
+               AND r.deleted_at IS NULL \
+             ORDER BY dc.updated_at DESC",
+        )
+        .bind(user_id)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+
+        let mut results = Vec::with_capacity(rows.len());
+        for (room_id, initiator_id, recipient_id, created_at) in rows {
+            let room_info = bus
+                .lookup_room(room_id)
+                .await
+                .unwrap_or_else(|_| RoomInfo::unknown(room_id));
+            let initiator_info = bus
+                .lookup_user(initiator_id)
+                .await
+                .unwrap_or_else(|_| UserInfo::unknown(initiator_id));
+            let recipient_info = bus
+                .lookup_user(recipient_id)
+                .await
+                .unwrap_or_else(|_| UserInfo::unknown(recipient_id));
+
+            results.push(dm::DmCreatedService {
+                room: room_info,
+                initiator: initiator_info,
+                recipient: recipient_info,
+                created_at,
+            });
+        }
+
+        Ok(Some(WsOutEvent::DmList { data: results }))
+    }
+}
diff --git a/lib/channel/http/handler/draft.rs b/lib/channel/http/handler/draft.rs
new file mode 100644
index 0000000..74e432b
--- /dev/null
+++ b/lib/channel/http/handler/draft.rs
@@ -0,0 +1,52 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, draft};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::{MAX_TEXT_LEN};
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn draft_save(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        content: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        if content.len() > MAX_TEXT_LEN {
+            return Err(ChannelError::Validation("draft too long".into()));
+        }
+        let key = format!("draft:{}:{}", user_id, room);
+        bus.inner.cache.set(&key, &content).await?;
+        let ds_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let ds_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = draft::DraftSavedService {
+            user: ds_user,
+            room: ds_room,
+            content,
+            saved_at: Utc::now(),
+        };
+        Ok(Some(WsOutEvent::DraftSaved { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn draft_clear(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let key = format!("draft:{}:{}", user_id, room);
+        bus.inner.cache.remove(&key).await?;
+        let dc_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let dc_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = draft::DraftClearedService {
+            user: dc_user,
+            room: dc_room,
+            cleared_at: Utc::now(),
+        };
+        Ok(Some(WsOutEvent::DraftCleared { room: data.room.clone(), data }))
+    }
+}
diff --git a/lib/channel/http/handler/forward.rs b/lib/channel/http/handler/forward.rs
new file mode 100644
index 0000000..5fb6085
--- /dev/null
+++ b/lib/channel/http/handler/forward.rs
@@ -0,0 +1,89 @@
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, forward};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn message_forward(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        source_message_id: Uuid,
+        target_room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let source = Self::load_message(bus, source_message_id).await?;
+
+        Self::ensure_room_access(bus, user_id, source.room).await?;
+        Self::ensure_room_access(bus, user_id, target_room).await?;
+
+        let seq = bus.inner.seq.seq(target_room).await?;
+        let sender = bus.lookup_user(user_id).await?;
+
+        let source_room_info = bus
+            .lookup_room(source.room)
+            .await
+            .unwrap_or_else(|_| RoomInfo::unknown(source.room));
+        let forward_content = format!(
+            "> Forwarded from {}:\n\n{}",
+            source_room_info.name, source.content
+        );
+
+        let metadata = serde_json::json!({
+            "source_room_id": source.room,
+            "source_message_id": source.id,
+            "source_room_name": source_room_info.name,
+            "forwarded_by": user_id,
+        });
+
+        let row = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "INSERT INTO room_message \
+             (room, seq, thread, parent, author, content, content_type, system_type, metadata) \
+             VALUES ($1, $2, NULL, NULL, $3, $4, 'forward', NULL, $5) \
+             RETURNING id, room, seq, thread, parent, author, content, content_type, pinned, \
+             system_type, metadata, edited_at, created_at, updated_at, deleted_at",
+        )
+        .bind(target_room)
+        .bind(seq)
+        .bind(user_id)
+        .bind(&forward_content)
+        .bind(&metadata)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+
+        let target_room_info = bus
+            .lookup_room(target_room)
+            .await
+            .unwrap_or_else(|_| RoomInfo::unknown(target_room));
+
+        let fwd_id = row.id;
+        let fwd_seq = row.seq;
+        let fwd_content = row.content.clone();
+        let fwd_content_type = row.content_type.clone();
+        let fwd_created_at = row.created_at;
+
+        bus.publish_room_message(
+            row,
+            Some(bus.lookup_user(user_id).await?),
+        )
+        .await?;
+
+        let data = forward::MessageForwardedService {
+            id: fwd_id,
+            seq: fwd_seq,
+            room: target_room_info.clone(),
+            sender,
+            content: fwd_content,
+            content_type: fwd_content_type,
+            source_room: source_room_info,
+            source_message_id: source.id,
+            forwarded_at: fwd_created_at,
+        };
+
+        Ok(Some(WsOutEvent::MessageForwarded {
+            room: target_room_info,
+            data,
+        }))
+    }
+}
diff --git a/lib/channel/http/handler/helpers.rs b/lib/channel/http/handler/helpers.rs
new file mode 100644
index 0000000..7a487d2
--- /dev/null
+++ b/lib/channel/http/handler/helpers.rs
@@ -0,0 +1,157 @@
+use std::collections::HashMap;
+
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, message, reaction};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn ensure_room_access(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<()> {
+        let rooms = crate::rooms::user_rooms(
+            &bus.inner.db,
+            &bus.inner.cache,
+            &bus.inner.config,
+            user_id,
+        )
+        .await?;
+        if rooms.contains(&room) {
+            Ok(())
+        } else {
+            Err(ChannelError::AccessDenied)
+        }
+    }
+
+    pub(super) async fn ensure_message_in_room(
+        bus: &ChannelBus,
+        room: Uuid,
+        message: Uuid,
+    ) -> ChannelResult<()> {
+        let exists: Option<(Uuid,)> = db::sqlx::query_as(
+            "SELECT id FROM room_message WHERE id = $1 AND room = $2 AND deleted_at IS NULL",
+        )
+        .bind(message)
+        .bind(room)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        exists.map(|_| ()).ok_or(ChannelError::RoomNotFound)
+    }
+
+    pub(super) async fn reaction_groups_for_messages(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        message_ids: &[Uuid],
+    ) -> ChannelResult<HashMap<Uuid, Vec<reaction::ReactionGroup>>> {
+        if message_ids.is_empty() {
+            return Ok(HashMap::new());
+        }
+
+        let rows = db::sqlx::query_as::<_, (Uuid, String, Uuid)>(
+            "SELECT message, reaction, \"user\" FROM room_reaction \
+             WHERE message = ANY($1) ORDER BY created_at ASC",
+        )
+        .bind(message_ids)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+
+        let user_ids: Vec<Uuid> = rows.iter().map(|(_, _, user)| *user).collect();
+        let users = bus.lookup_users(&user_ids).await.unwrap_or_default();
+        let mut grouped: HashMap<Uuid, HashMap<String, reaction::ReactionGroup>> =
+            HashMap::new();
+
+        for (message_id, emoji, reactor) in rows {
+            let group = grouped
+                .entry(message_id)
+                .or_default()
+                .entry(emoji.clone())
+                .or_insert_with(|| reaction::ReactionGroup {
+                    emoji: emoji.clone(),
+                    count: 0,
+                    reacted_by_me: false,
+                    users: Vec::new(),
+                });
+            group.count += 1;
+            group.reacted_by_me |= reactor == user_id;
+            group.users.push(
+                users
+                    .get(&reactor)
+                    .cloned()
+                    .unwrap_or_else(|| UserInfo::unknown(reactor)),
+            );
+        }
+
+        Ok(grouped
+            .into_iter()
+            .map(|(message_id, groups)| {
+                (message_id, groups.into_values().collect::<Vec<_>>())
+            })
+            .collect())
+    }
+
+    pub(super) async fn ensure_workspace_member(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        wk: Uuid,
+    ) -> ChannelResult<()> {
+        let row: Option<(Uuid,)> = db::sqlx::query_as(
+            "SELECT wk FROM wk_member WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+        )
+        .bind(wk)
+        .bind(user_id)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        row.map(|_| ()).ok_or(ChannelError::AccessDenied)
+    }
+
+    #[allow(dead_code)]
+    pub(super) fn missed_message_data(
+        m: crate::MissedMessage,
+    ) -> message::MessageNewService {
+        message::MessageNewService {
+            id: m.message_id,
+            seq: m.seq,
+            room: RoomInfo::unknown(m.room_id),
+            sender_type: "user".to_string(),
+            sender: UserInfo::unknown(m.sender_id),
+            thread: None,
+            in_reply_to: None,
+            content: m.content,
+            content_type: "text".to_string(),
+            pinned: false,
+            system_type: None,
+            metadata: serde_json::Value::Null,
+            thinking_content: None,
+            thinking_is_chunked: None,
+            send_at: m.send_at,
+            reactions: vec![],
+        }
+    }
+    #[allow(dead_code)]
+    pub(super) fn message_data(
+        m: model::room::RoomMessageModel,
+    ) -> message::MessageNewService {
+        message::MessageNewService {
+            id: m.id,
+            seq: m.seq,
+            room: RoomInfo::unknown(m.room),
+            sender_type: "user".to_string(),
+            sender: UserInfo::unknown(m.author),
+            thread: m.thread,
+            in_reply_to: m.parent,
+            content: m.content,
+            content_type: m.content_type,
+            pinned: m.pinned,
+            system_type: m.system_type,
+            metadata: m.metadata,
+            thinking_content: None,
+            thinking_is_chunked: None,
+            send_at: m.created_at,
+            reactions: vec![],
+        }
+    }
+}
diff --git a/lib/channel/http/handler/invite.rs b/lib/channel/http/handler/invite.rs
new file mode 100644
index 0000000..cde04e0
--- /dev/null
+++ b/lib/channel/http/handler/invite.rs
@@ -0,0 +1,123 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo, invite};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn invite_create(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        workspace: Uuid,
+        _room: Option<Uuid>,
+        _max_uses: Option<i32>,
+        _expires_at: Option<chrono::DateTime<chrono::Utc>>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_workspace_member(bus, user_id, workspace).await?;
+        let invite_id = Uuid::now_v7();
+        let code = Uuid::now_v7().to_string();
+        let id_key = format!("invite:id:{}", invite_id);
+        let code_key = format!("invite:code:{}", code);
+        let meta = serde_json::json!({
+            "workspace": workspace,
+            "created_by": user_id,
+            "room": _room,
+            "max_uses": _max_uses,
+            "expires_at": _expires_at,
+        });
+        bus.inner.cache.set(&id_key, &meta.to_string()).await?;
+        bus.inner.cache.set(&code_key, &invite_id.to_string()).await?;
+        let inv_room = match _room {
+            Some(r) => Some(bus.lookup_room(r).await.unwrap_or_else(|_| RoomInfo::unknown(r))),
+            None => None,
+        };
+        let data = invite::InviteCreatedService {
+            id: invite_id,
+            workspace: bus.lookup_workspace(workspace).await.unwrap_or_else(|_| WorkspaceInfo::unknown(workspace)),
+            room: inv_room,
+            inviter: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+            invitee: None,
+            code,
+            max_uses: _max_uses,
+            expires_at: _expires_at,
+            created_at: Utc::now(),
+        };
+        Ok(Some(WsOutEvent::InviteCreated { data }))
+    }
+
+    pub(super) async fn invite_accept(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        code: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let code_key = format!("invite:code:{}", code);
+        let invite_id_str: Option<String> = bus.inner.cache.get(&code_key).await?;
+        let invite_id = invite_id_str
+            .as_deref()
+            .and_then(|s| Uuid::parse_str(s).ok())
+            .ok_or(ChannelError::RoomNotFound)?;
+        let id_key = format!("invite:id:{}", invite_id);
+        let stored: Option<String> = bus.inner.cache.get(&id_key).await?;
+        let meta: serde_json::Value = stored
+            .as_deref()
+            .and_then(|s| serde_json::from_str(s).ok())
+            .ok_or(ChannelError::RoomNotFound)?;
+        let wk = meta["workspace"]
+            .as_str()
+            .and_then(|s| Uuid::parse_str(s).ok())
+            .ok_or(ChannelError::RoomNotFound)?;
+        db::sqlx::query(
+            "INSERT INTO wk_member (wk, \"user\", owner, admin, join_at) \
+             VALUES ($1, $2, false, false, now()) \
+             ON CONFLICT DO NOTHING",
+        )
+        .bind(wk)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        db::sqlx::query(
+            "INSERT INTO wk_apply_join (wk, \"user\", status, created_at, updated_at) \
+             VALUES ($1, $2, 'accepted', now(), now())",
+        )
+        .bind(wk)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        bus.inner.cache.remove(&code_key).await?;
+        bus.inner.cache.remove(&id_key).await?;
+        let data = invite::InviteAcceptedService {
+            id: Uuid::now_v7(),
+            workspace: bus.lookup_workspace(wk).await.unwrap_or_else(|_| WorkspaceInfo::unknown(wk)),
+            room: None,
+            user: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+            accepted_at: Utc::now(),
+        };
+        bus.workspace_changed(wk).await?;
+        Ok(Some(WsOutEvent::InviteAccepted { data }))
+    }
+
+    pub(super) async fn invite_revoke(
+        bus: &ChannelBus,
+        _user_id: Uuid,
+        id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let id_key = format!("invite:id:{}", id);
+        let stored: Option<String> = bus.inner.cache.get(&id_key).await?;
+        let meta: serde_json::Value = stored
+            .as_deref()
+            .and_then(|s| serde_json::from_str(s).ok())
+            .ok_or(ChannelError::RoomNotFound)?;
+        let created_by = meta["created_by"]
+            .as_str()
+            .and_then(|s| Uuid::parse_str(s).ok())
+            .ok_or(ChannelError::RoomNotFound)?;
+        if created_by != _user_id {
+            return Err(ChannelError::AccessDenied);
+        }
+        bus.inner.cache.remove(&id_key).await?;
+        Ok(None)
+    }
+}
diff --git a/lib/channel/http/handler/message.rs b/lib/channel/http/handler/message.rs
new file mode 100644
index 0000000..de60d10
--- /dev/null
+++ b/lib/channel/http/handler/message.rs
@@ -0,0 +1,590 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, message, thread};
+use crate::{
+    ChannelBus, ChannelError, ChannelResult,
+    pagination::{MessagePagination, PaginationDirection, PaginationParams},
+};
+
+use super::{MAX_MESSAGES_PER_REQUEST, MAX_TEXT_LEN};
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    /// Count non-deleted sibling replies to the same parent message.
+    async fn count_sibling_replies(
+        bus: &ChannelBus,
+        parent_id: Uuid,
+    ) -> ChannelResult<i64> {
+        let (count,): (i64,) = db::sqlx::query_as(
+            "SELECT COUNT(*) FROM room_message WHERE parent = $1 AND deleted_at IS NULL",
+        )
+        .bind(parent_id)
+        .fetch_one(bus.inner.db.reader())
+        .await?;
+        Ok(count)
+    }
+
+    /// Walk the reply parent chain and return (root_message_id, root_message_seq, chain_depth).
+    async fn reply_chain_info(
+        bus: &ChannelBus,
+        parent_id: Uuid,
+    ) -> ChannelResult<(Uuid, i64, i32)> {
+        let rows: Vec<(Uuid, i64, i32)> = db::sqlx::query_as(
+            r#"WITH RECURSIVE chain AS (
+                SELECT id, parent, seq, 1 AS depth
+                FROM room_message
+                WHERE id = $1 AND deleted_at IS NULL
+                UNION ALL
+                SELECT m.id, m.parent, m.seq, c.depth + 1
+                FROM room_message m
+                JOIN chain c ON m.id = c.parent
+                WHERE m.deleted_at IS NULL
+            )
+            SELECT id, seq, depth FROM chain ORDER BY depth DESC"#,
+        )
+        .bind(parent_id)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+
+        let root_id = rows.first().map(|r| r.0).unwrap_or(parent_id);
+        let root_seq = rows.first().map(|r| r.1).unwrap_or(0);
+        let max_depth = rows.first().map(|r| r.2).unwrap_or(1);
+        Ok((root_id, root_seq, max_depth))
+    }
+
+    /// Check if any message in the reply parent chain already belongs to a thread.
+    async fn find_thread_in_chain(
+        bus: &ChannelBus,
+        parent_id: Uuid,
+    ) -> ChannelResult<Option<Uuid>> {
+        let row: Option<(Uuid,)> = db::sqlx::query_as(
+            r#"WITH RECURSIVE chain AS (
+                SELECT id, parent, thread
+                FROM room_message
+                WHERE id = $1 AND deleted_at IS NULL
+                UNION ALL
+                SELECT m.id, m.parent, m.thread
+                FROM room_message m
+                JOIN chain c ON m.id = c.parent
+                WHERE m.deleted_at IS NULL
+            )
+            SELECT thread FROM chain WHERE thread IS NOT NULL LIMIT 1"#,
+        )
+        .bind(parent_id)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        Ok(row.map(|r| r.0))
+    }
+
+    /// Update all messages in the reply parent chain to point to the given thread.
+    async fn attach_chain_to_thread(
+        bus: &ChannelBus,
+        parent_id: Uuid,
+        thread_id: Uuid,
+    ) -> ChannelResult<()> {
+        db::sqlx::query(
+            r#"WITH RECURSIVE chain AS (
+                SELECT id FROM room_message
+                WHERE id = $1 AND deleted_at IS NULL
+                UNION ALL
+                SELECT m.id FROM room_message m
+                JOIN chain c ON m.id = c.parent
+                WHERE m.deleted_at IS NULL
+            )
+            UPDATE room_message SET thread = $2, updated_at = now()
+            WHERE id IN (SELECT id FROM chain) AND thread IS NULL"#,
+        )
+        .bind(parent_id)
+        .bind(thread_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        Ok(())
+    }
+
+    pub(super) async fn message_create(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        content: String,
+        content_type: Option<String>,
+        thread: Option<Uuid>,
+        in_reply_to: Option<Uuid>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        if content.len() > MAX_TEXT_LEN {
+            return Err(ChannelError::Validation(
+                "message exceeds maximum length".to_string(),
+            ));
+        }
+        if let Some(parent_message) = in_reply_to {
+            Self::ensure_message_in_room(bus, room, parent_message).await?;
+        }
+
+        // ── Auto-thread logic ──────────────────────────────────────────
+        let mut events: Vec<WsOutEvent> = Vec::new();
+        let effective_thread: Option<Uuid> = if let Some(ref parent_id) = in_reply_to {
+            if thread.is_some() {
+                thread
+            } else {
+                let existing = Self::find_thread_in_chain(bus, *parent_id).await?;
+                if let Some(tid) = existing {
+                    Some(tid)
+                } else {
+                    let sibling_count = Self::count_sibling_replies(bus, *parent_id).await?;
+                    let (root_id, root_seq, chain_depth) = Self::reply_chain_info(bus, *parent_id).await?;
+                    let should_create = sibling_count >= 3 || chain_depth >= 5;
+
+                    if should_create {
+                        let seq = bus.inner.seq.seq(room).await?;
+                        let thread_row = db::sqlx::query_as::<_, model::room::RoomThreadModel>(
+                            "INSERT INTO room_thread (room, seq, starter_message, title, created_by, created_at, updated_at) \
+                             VALUES ($1, $2, $3, '', $4, now(), now()) \
+                             RETURNING id, room, seq, starter_message, title, created_by, archived, locked, \
+                             last_message_at, created_at, updated_at, archived_at",
+                        )
+                        .bind(room)
+                        .bind(seq)
+                        .bind(root_id)  // UUID of the root message
+                        .bind(user_id)
+                        .fetch_one(bus.inner.db.writer())
+                        .await?;
+
+                        let new_thread_id = thread_row.id;
+                        Self::attach_chain_to_thread(bus, *parent_id, new_thread_id).await?;
+
+                        let tc_room = bus.lookup_room(room).await
+                            .unwrap_or_else(|_| RoomInfo::unknown(room));
+                        let created_by = bus.lookup_user(user_id).await
+                            .unwrap_or_else(|_| UserInfo::unknown(user_id));
+                        let data = thread::ThreadCreatedService {
+                            id: new_thread_id,
+                            room: tc_room,
+                            parent: root_seq,
+                            created_by,
+                            participants: serde_json::Value::Null,
+                            created_at: thread_row.created_at,
+                        };
+                        bus.publish_room_event(room, "thread.created", &data).await?;
+                        events.push(WsOutEvent::ThreadCreated {
+                            room: data.room.clone(),
+                            data,
+                        });
+
+                        Some(new_thread_id)
+                    } else {
+                        None
+                    }
+                }
+            }
+        } else {
+            thread
+        };
+        // ── End auto-thread logic ──────────────────────────────────────
+
+        if let Some(thread_id) = effective_thread {
+            let exists: Option<(Uuid,)> = db::sqlx::query_as(
+                "SELECT id FROM room_thread WHERE id = $1 AND room = $2",
+            )
+            .bind(thread_id)
+            .bind(room)
+            .fetch_optional(bus.inner.db.reader())
+            .await?;
+            if exists.is_none() {
+                return Err(ChannelError::RoomNotFound);
+            }
+        }
+
+        let seq = bus.inner.seq.seq(room).await?;
+        let sender = bus.lookup_user(user_id).await?;
+        let sender_for_response = sender.clone();
+        let row = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "INSERT INTO room_message (room, seq, thread, parent, author, content, content_type) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7) \
+             RETURNING id, room, seq, thread, parent, author, content, content_type, pinned, \
+             system_type, metadata, edited_at, created_at, updated_at, deleted_at",
+        )
+        .bind(room)
+        .bind(seq)
+        .bind(effective_thread)
+        .bind(in_reply_to)
+        .bind(user_id)
+        .bind(content)
+        .bind(content_type.unwrap_or_else(|| "text".to_string()))
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+
+        bus.publish_room_message(
+            row.clone(),
+            Some(sender),
+        ).await?;
+        let msg_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        events.push(WsOutEvent::MessageNew {
+            room: msg_room.clone(),
+            data: message::MessageNewService {
+                id: row.id,
+                seq: row.seq,
+                room: msg_room,
+                sender_type: "user".to_string(),
+                sender: sender_for_response,
+                thread: row.thread,
+                in_reply_to: row.parent,
+                content: row.content,
+                content_type: row.content_type,
+                pinned: row.pinned,
+                system_type: row.system_type,
+                metadata: row.metadata,
+                thinking_content: None,
+                thinking_is_chunked: None,
+                send_at: row.created_at,
+                reactions: vec![],
+            },
+        });
+
+        Ok(events.into_iter().find(|e| matches!(e, WsOutEvent::MessageNew { .. })))
+    }
+
+    pub(super) async fn message_update(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        message_id: Uuid,
+        content: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        if content.len() > MAX_TEXT_LEN {
+            return Err(ChannelError::Validation(
+                "message exceeds maximum length".to_string(),
+            ));
+        }
+        let room_id: (Uuid,) =
+            db::sqlx::query_as("SELECT room FROM room_message WHERE id = $1 AND deleted_at IS NULL")
+                .bind(message_id)
+                .fetch_optional(bus.inner.db.reader())
+                .await?
+                .ok_or(ChannelError::RoomNotFound)?;
+        Self::ensure_room_access(bus, user_id, room_id.0).await?;
+
+        let old = Self::load_message(bus, message_id).await?;
+        if old.author != user_id {
+            return Err(ChannelError::Unauthorized);
+        }
+        let row = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "UPDATE room_message SET content = $2, edited_at = now(), updated_at = now() \
+             WHERE id = $1 AND deleted_at IS NULL \
+             RETURNING id, room, seq, thread, parent, author, content, content_type, pinned, \
+             system_type, metadata, edited_at, created_at, updated_at, deleted_at",
+        )
+        .bind(message_id)
+        .bind(content)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        db::sqlx::query(
+            "INSERT INTO room_message_edit_history (message, seq, editor, old_content, new_content) \
+             VALUES ($1, $2, $3, $4, $5)",
+        )
+        .bind(message_id)
+        .bind(row.seq)
+        .bind(user_id)
+        .bind(old.content)
+        .bind(row.content.clone())
+        .execute(bus.inner.db.writer())
+        .await?;
+
+        let sender = bus.lookup_user(row.author).await.unwrap_or_else(|_| UserInfo::unknown(row.author));
+        let room = bus.lookup_room(row.room).await.unwrap_or_else(|_| RoomInfo::unknown(row.room));
+        let data = message::MessageEditedService {
+            id: row.id,
+            seq: row.seq,
+            room,
+            sender,
+            content: row.content,
+            edited_at: row.edited_at.unwrap_or_else(Utc::now),
+        };
+        bus.publish_room_event(row.room, "message.edited", &data)
+            .await?;
+        Ok(Some(WsOutEvent::MessageEdited {
+            room: data.room.clone(),
+            data,
+        }))
+    }
+
+    pub(super) async fn message_revoke(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        message_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let room_id: (Uuid,) =
+            db::sqlx::query_as("SELECT room FROM room_message WHERE id = $1 AND deleted_at IS NULL")
+                .bind(message_id)
+                .fetch_optional(bus.inner.db.reader())
+                .await?
+                .ok_or(ChannelError::RoomNotFound)?;
+        Self::ensure_room_access(bus, user_id, room_id.0).await?;
+        let old = Self::load_message(bus, message_id).await?;
+        if old.author != user_id {
+            return Err(ChannelError::Unauthorized);
+        }
+        if let Some(window_secs) = bus.inner.config.revoke_window_secs {
+            let elapsed = Utc::now().signed_duration_since(old.created_at);
+            if elapsed.num_seconds() > window_secs as i64 {
+                return Err(ChannelError::Validation(
+                    "message revoke window expired".to_string(),
+                ));
+            }
+        }
+        let row = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "UPDATE room_message SET deleted_at = now(), updated_at = now() \
+             WHERE id = $1 AND deleted_at IS NULL \
+             RETURNING id, room, seq, thread, parent, author, content, content_type, pinned, \
+             system_type, metadata, edited_at, created_at, updated_at, deleted_at",
+        )
+        .bind(message_id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let revoked_by = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let room = bus.lookup_room(row.room).await.unwrap_or_else(|_| RoomInfo::unknown(row.room));
+        let data = message::MessageRevokedService {
+            id: row.id,
+            seq: row.seq,
+            room,
+            revoked_by,
+            revoked_at: row.deleted_at.unwrap_or_else(Utc::now),
+        };
+        bus.publish_room_event(row.room, "message.revoked", &data)
+            .await?;
+        Ok(Some(WsOutEvent::MessageRevoked {
+            room: data.room.clone(),
+            data,
+        }))
+    }
+
+    pub(super) async fn load_message(
+        bus: &ChannelBus,
+        message_id: Uuid,
+    ) -> ChannelResult<model::room::RoomMessageModel> {
+        db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "SELECT id, room, seq, thread, parent, author, content, content_type, pinned, \
+             system_type, metadata, edited_at, created_at, updated_at, deleted_at \
+             FROM room_message WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(message_id)
+        .fetch_one(bus.inner.db.reader())
+        .await
+        .map_err(|e| match e {
+            db::sqlx::Error::RowNotFound => ChannelError::RoomNotFound,
+            other => ChannelError::Database(other),
+        })
+    }
+
+    pub(super) async fn message_list(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        before_seq: Option<i64>,
+        after_seq: Option<i64>,
+        limit: Option<u64>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let limit = limit.unwrap_or(MAX_MESSAGES_PER_REQUEST);
+        let direction = if before_seq.is_some() {
+            PaginationDirection::Before
+        } else {
+            PaginationDirection::After
+        };
+        let cursor = before_seq
+            .map(|s| s.to_string())
+            .or(after_seq.map(|s| s.to_string()));
+
+        let pagination = MessagePagination::new(bus.inner.db.clone());
+        let page = pagination
+            .get_messages(PaginationParams {
+                room_id: room,
+                limit,
+                cursor,
+                direction,
+            })
+            .await?;
+
+        let mut page_messages = page.messages;
+        if before_seq.is_some() || (before_seq.is_none() && after_seq.is_none()) {
+            page_messages.reverse();
+        }
+        let message_ids: Vec<Uuid> = page_messages.iter().map(|m| m.id).collect();
+        let reactions = Self::reaction_groups_for_messages(bus, user_id, &message_ids)
+            .await
+            .unwrap_or_default();
+
+        let list_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+
+        let mut messages: Vec<message::MessageNewService> =
+            Vec::with_capacity(page_messages.len());
+        for m in page_messages {
+            let sender = bus.lookup_user(m.sender_id).await
+                .unwrap_or_else(|_| UserInfo::unknown(m.sender_id));
+            messages.push(message::MessageNewService {
+                id: m.id,
+                seq: m.seq,
+                room: list_room.clone(),
+                sender_type: "user".to_string(),
+                sender,
+                thread: m.thread,
+                in_reply_to: m.parent,
+                content: m.content,
+                content_type: m.content_type,
+                pinned: m.pinned,
+                system_type: m.system_type,
+                metadata: m.metadata,
+                thinking_content: None,
+                thinking_is_chunked: None,
+                send_at: m.send_at,
+                reactions: reactions.get(&m.id).cloned().unwrap_or_default(),
+            });
+        }
+
+        let total = messages.len() as i64;
+        Ok(Some(WsOutEvent::MessageList {
+            room: list_room.clone(),
+            data: message::MessageListService {
+                room: list_room,
+                messages,
+                total,
+            },
+        }))
+    }
+
+    pub(super) async fn message_around(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        seq: i64,
+        limit: Option<u64>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let size = limit
+            .unwrap_or(MAX_MESSAGES_PER_REQUEST)
+            .min(MAX_MESSAGES_PER_REQUEST) as i64;
+        let rows = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "(SELECT id, room, seq, thread, parent, author, content, content_type, pinned, \
+               system_type, metadata, edited_at, created_at, updated_at, deleted_at \
+               FROM room_message \
+               WHERE room = $1 AND seq < $2 AND deleted_at IS NULL \
+               ORDER BY seq DESC LIMIT $3) \
+             UNION ALL \
+             (SELECT id, room, seq, thread, parent, author, content, content_type, pinned, \
+               system_type, metadata, edited_at, created_at, updated_at, deleted_at \
+               FROM room_message \
+               WHERE room = $1 AND seq >= $2 AND deleted_at IS NULL \
+               ORDER BY seq ASC LIMIT $3) \
+             ORDER BY seq ASC",
+        )
+        .bind(room)
+        .bind(seq)
+        .bind(size)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+        let author_ids: Vec<Uuid> = rows.iter().map(|r| r.author).collect();
+        let user_map = bus.lookup_users(&author_ids).await.unwrap_or_default();
+        let message_ids: Vec<Uuid> = rows.iter().map(|r| r.id).collect();
+        let reactions = Self::reaction_groups_for_messages(bus, user_id, &message_ids)
+            .await
+            .unwrap_or_default();
+        let around_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let messages = rows
+            .into_iter()
+            .map(|r| {
+                let sender = user_map
+                    .get(&r.author)
+                    .cloned()
+                    .unwrap_or_else(|| UserInfo::unknown(r.author));
+                message::MessageNewService {
+                    id: r.id,
+                    seq: r.seq,
+                    room: around_room.clone(),
+                    sender_type: "user".to_string(),
+                    sender,
+                    thread: r.thread,
+                    in_reply_to: r.parent,
+                    content: r.content,
+                    content_type: r.content_type,
+                    pinned: r.pinned,
+                    system_type: r.system_type,
+                    metadata: r.metadata,
+                    thinking_content: None,
+                    thinking_is_chunked: None,
+                    send_at: r.created_at,
+                    reactions: reactions.get(&r.id).cloned().unwrap_or_default(),
+                }
+            })
+            .collect::<Vec<_>>();
+        let total = messages.len() as i64;
+        Ok(Some(WsOutEvent::MessageList {
+            room: around_room.clone(),
+            data: message::MessageListService {
+                room: around_room,
+                messages,
+                total,
+            },
+        }))
+    }
+
+    pub(super) async fn missed_messages(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        after_seq: i64,
+        limit: Option<i64>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let limit =
+            limit.unwrap_or(MAX_MESSAGES_PER_REQUEST as i64).max(0) as usize;
+        let messages = bus
+            .inner
+            .reconnect
+            .get_missed_messages(room, after_seq)
+            .await?;
+        let author_ids: Vec<Uuid> = messages.iter().map(|m| m.sender_id).collect();
+        let message_ids: Vec<Uuid> = messages.iter().map(|m| m.message_id).collect();
+        let user_map = bus.lookup_users(&author_ids).await.unwrap_or_default();
+        let reactions = Self::reaction_groups_for_messages(bus, user_id, &message_ids)
+            .await
+            .unwrap_or_default();
+        let missed_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let messages = messages
+            .into_iter()
+            .take(limit)
+            .map(|m| {
+                let sender = user_map
+                    .get(&m.sender_id)
+                    .cloned()
+                    .unwrap_or_else(|| UserInfo::unknown(m.sender_id));
+                message::MessageNewService {
+                    id: m.message_id,
+                    seq: m.seq,
+                    room: missed_room.clone(),
+                    sender_type: "user".to_string(),
+                    sender,
+                    thread: None,
+                    in_reply_to: None,
+                    content: m.content,
+                    content_type: "text".to_string(),
+                    pinned: false,
+                    system_type: None,
+                    metadata: serde_json::Value::Null,
+                    thinking_content: None,
+                    thinking_is_chunked: None,
+                    send_at: m.send_at,
+                    reactions: reactions.get(&m.message_id).cloned().unwrap_or_default(),
+                }
+            })
+            .collect::<Vec<_>>();
+        let data = message::MessageListService {
+            room: missed_room.clone(),
+            total: messages.len() as i64,
+            messages,
+        };
+        Ok(Some(WsOutEvent::MessageList {
+            room: missed_room,
+            data,
+        }))
+    }
+}
diff --git a/lib/channel/http/handler/message_read.rs b/lib/channel/http/handler/message_read.rs
new file mode 100644
index 0000000..5d849b6
--- /dev/null
+++ b/lib/channel/http/handler/message_read.rs
@@ -0,0 +1,127 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, message_read};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn message_mark_read(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        message_ids: Vec<Uuid>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+
+        if message_ids.is_empty() {
+            return Ok(None);
+        }
+
+        let now = Utc::now();
+        db::sqlx::query(
+            "INSERT INTO message_read (message, room, \"user\", read_at) \
+             SELECT m.id, m.room, $1, $2 \
+             FROM room_message m \
+             WHERE m.id = ANY($3) AND m.room = $4 AND m.deleted_at IS NULL \
+             ON CONFLICT (message, \"user\") DO NOTHING",
+        )
+        .bind(user_id)
+        .bind(now)
+        .bind(&message_ids)
+        .bind(room)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let max_seq_row: Option<(i64,)> = db::sqlx::query_as(
+            "SELECT MAX(seq) FROM room_message \
+             WHERE id = ANY($1) AND room = $2 AND deleted_at IS NULL",
+        )
+        .bind(&message_ids)
+        .bind(room)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        let max_seq = max_seq_row.map(|r| r.0).unwrap_or(0);
+
+        if max_seq > 0 {
+            db::sqlx::query(
+                "INSERT INTO user_room_state (\"user\", room, last_read_seq, last_read_at, updated_at) \
+                 VALUES ($1, $2, $3, $4, $4) \
+                 ON CONFLICT (\"user\", room) DO UPDATE \
+                 SET last_read_seq = GREATEST(user_room_state.last_read_seq, $3), \
+                     last_read_at = $4, updated_at = $4",
+            )
+            .bind(user_id)
+            .bind(room)
+            .bind(max_seq)
+            .bind(now)
+            .execute(bus.inner.db.writer())
+            .await?;
+        }
+
+        let room_info =
+            bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let reader_info =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+        let data = message_read::MessageReadBatchService {
+            room: room_info.clone(),
+            message_ids,
+            last_seq: max_seq,
+            reader: reader_info,
+            read_at: now,
+        };
+        bus.publish_room_event(room, "message.read_batch", &data).await?;
+        Ok(Some(WsOutEvent::MessageReadBatch {
+            room: room_info,
+            data,
+        }))
+    }
+    pub(super) async fn message_get_readers(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        message_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let msg_room: Option<(Uuid, Uuid)> = db::sqlx::query_as(
+            "SELECT room, seq FROM room_message WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(message_id)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+
+        let Some((room, _seq)) = msg_room else {
+            return Err(crate::ChannelError::RoomNotFound);
+        };
+        Self::ensure_room_access(bus, user_id, room).await?;
+
+        let rows = db::sqlx::query_as::<_, (Uuid, chrono::DateTime<Utc>)>(
+            "SELECT \"user\", read_at FROM message_read \
+             WHERE message = $1 ORDER BY read_at ASC",
+        )
+        .bind(message_id)
+        .fetch_all(bus.inner.db.reader())
+        .await?;
+
+        let user_ids: Vec<Uuid> = rows.iter().map(|(uid, _)| *uid).collect();
+        let users = bus.lookup_users(&user_ids).await.unwrap_or_default();
+
+        let readers: Vec<message_read::MessageReaderEntry> = rows
+            .into_iter()
+            .map(|(uid, read_at)| message_read::MessageReaderEntry {
+                user: users
+                    .get(&uid)
+                    .cloned()
+                    .unwrap_or_else(|| UserInfo::unknown(uid)),
+                read_at,
+            })
+            .collect();
+
+        Ok(Some(WsOutEvent::MessageReaders {
+            data: message_read::MessageReadersService {
+                message_id,
+                readers,
+            },
+        }))
+    }
+}
diff --git a/lib/channel/http/handler/mod.rs b/lib/channel/http/handler/mod.rs
new file mode 100644
index 0000000..4ba1406
--- /dev/null
+++ b/lib/channel/http/handler/mod.rs
@@ -0,0 +1,336 @@
+use uuid::Uuid;
+
+use crate::{ChannelBus, ChannelResult};
+
+pub(crate) use super::out_event::WsOutEvent;
+use super::types::{WS_PROTOCOL_VERSION, WsInMessage};
+
+pub(crate) const MAX_TEXT_LEN: usize = 64 * 1024;
+pub(crate) const MAX_MESSAGES_PER_REQUEST: u64 = 100;
+pub(crate) const MAX_ROOM_NAME_LEN: usize = 100;
+pub(crate) const MAX_CATEGORY_NAME_LEN: usize = 50;
+
+mod helpers;
+
+mod subscription;
+mod message;
+mod room;
+mod category;
+mod reaction;
+mod thread;
+mod pin;
+mod draft;
+mod notification;
+mod presence;
+mod invite;
+mod ban;
+mod voice;
+mod ai;
+mod search;
+mod user;
+mod conversation;
+mod dm;
+mod forward;
+mod message_read;
+mod star;
+
+pub struct WsHandler;
+
+impl WsHandler {
+    pub async fn handle(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        msg: WsInMessage,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        match msg {
+            WsInMessage::Ping => Ok(Some(WsOutEvent::Pong {
+                protocol_version: WS_PROTOCOL_VERSION,
+            })),
+            WsInMessage::Subscribe { room } => {
+                Self::subscribe(bus, user_id, room).await
+            }
+            WsInMessage::Unsubscribe { room } => {
+                Self::unsubscribe(bus, user_id, room).await
+            }
+            WsInMessage::TypingStart { room } => {
+                Self::typing(bus, room, user_id, "start").await
+            }
+            WsInMessage::TypingStop { room } => {
+                Self::typing(bus, room, user_id, "stop").await
+            }
+            WsInMessage::ReadReceipt {
+                room,
+                last_read_seq,
+            } => Self::read_receipt(bus, user_id, room, last_read_seq).await,
+            WsInMessage::MessageList {
+                room,
+                before_seq,
+                after_seq,
+                limit,
+            } => {
+                Self::message_list(
+                    bus, user_id, room, before_seq, after_seq, limit,
+                )
+                .await
+            }
+            WsInMessage::MessageAround { room, seq, limit } => {
+                Self::message_around(bus, user_id, room, seq, limit).await
+            }
+            WsInMessage::MessageCreate {
+                room,
+                content,
+                content_type,
+                thread,
+                in_reply_to,
+            } => {
+                Self::message_create(
+                    bus,
+                    user_id,
+                    room,
+                    content,
+                    content_type,
+                    thread,
+                    in_reply_to,
+                )
+                .await
+            }
+            WsInMessage::MessageUpdate { message, content } => {
+                Self::message_update(bus, user_id, message, content).await
+            }
+            WsInMessage::MessageRevoke { message } => {
+                Self::message_revoke(bus, user_id, message).await
+            }
+            WsInMessage::RoomGet { room } => {
+                Self::room_get(bus, user_id, room).await
+            }
+            WsInMessage::RoomCreate {
+                workspace,
+                room_name,
+                public,
+                category,
+            } => {
+                Self::room_create(
+                    bus, user_id, workspace, room_name, public, category,
+                )
+                .await
+            }
+            WsInMessage::RoomUpdate {
+                room,
+                room_name,
+                public,
+                category,
+            } => Self::room_update(bus, user_id, room, room_name, public, category).await,
+            WsInMessage::RoomDelete { room } => {
+                Self::room_delete(bus, user_id, room).await
+            }
+            WsInMessage::CategoryCreate {
+                workspace,
+                name,
+                position,
+            } => Self::category_create(bus, user_id, workspace, name, position).await,
+            WsInMessage::CategoryUpdate { id, name, position } => {
+                Self::category_update(bus, user_id, id, name, position).await
+            }
+            WsInMessage::CategoryDelete { id } => {
+                Self::category_delete(bus, user_id, id).await
+            }
+            WsInMessage::AccessGrant { room, user } => {
+                Self::access_grant(bus, user_id, room, user).await
+            }
+            WsInMessage::AccessRevoke { room, user } => {
+                Self::access_revoke(bus, user_id, room, user).await
+            }
+            WsInMessage::StateSetReadSeq {
+                room,
+                last_read_seq,
+            } => Self::read_receipt(bus, user_id, room, last_read_seq).await,
+            WsInMessage::MissedMessages {
+                room,
+                after_seq,
+                limit,
+            } => {
+                Self::missed_messages(bus, user_id, room, after_seq, limit)
+                    .await
+            }
+            WsInMessage::CsrfToken => Self::csrf_token(bus, user_id).await,
+            WsInMessage::StateUpdateDnd {
+                room,
+                do_not_disturb,
+                dnd_start_hour,
+                dnd_end_hour,
+            } => {
+                Self::dnd_update(
+                    bus, user_id, room, do_not_disturb, dnd_start_hour,
+                    dnd_end_hour,
+                )
+                .await
+            }
+            WsInMessage::ReactionAdd {
+                room,
+                message,
+                emoji,
+            } => Self::reaction_add(bus, user_id, room, message, emoji).await,
+            WsInMessage::ReactionRemove {
+                room,
+                message,
+                emoji,
+            } => {
+                Self::reaction_remove(bus, user_id, room, message, emoji).await
+            }
+            WsInMessage::ThreadCreate { room, parent } => {
+                Self::thread_create(bus, user_id, room, parent).await
+            }
+            WsInMessage::ThreadResolve { thread_id } => {
+                Self::thread_resolve(bus, user_id, thread_id).await
+            }
+            WsInMessage::ThreadArchive { thread_id } => {
+                Self::thread_archive(bus, user_id, thread_id).await
+            }
+            WsInMessage::PinAdd { room, message } => {
+                Self::pin_add(bus, user_id, room, message).await
+            }
+            WsInMessage::PinRemove { room, message } => {
+                Self::pin_remove(bus, user_id, room, message).await
+            }
+            WsInMessage::DraftSave { room, content } => {
+                Self::draft_save(bus, user_id, room, content).await
+            }
+            WsInMessage::DraftClear { room } => {
+                Self::draft_clear(bus, user_id, room).await
+            }
+            WsInMessage::NotificationMarkRead { id } => {
+                Self::notification_mark_read(bus, user_id, id).await
+            }
+            WsInMessage::NotificationMarkAllRead { workspace_id } => {
+                Self::notification_mark_all_read(bus, user_id, workspace_id).await
+            }
+            WsInMessage::NotificationArchive { id } => {
+                Self::notification_archive(bus, user_id, id).await
+            }
+            WsInMessage::PresenceUpdate { status } => {
+                Self::presence_update(bus, user_id, status).await
+            }
+            WsInMessage::CustomStatusUpdate {
+                emoji,
+                text,
+                expires_at,
+            } => {
+                Self::custom_status_update(bus, user_id, emoji, text, expires_at)
+                    .await
+            }
+            WsInMessage::InviteCreate {
+                workspace,
+                room,
+                max_uses,
+                expires_at,
+            } => {
+                Self::invite_create(bus, user_id, workspace, room, max_uses, expires_at)
+                    .await
+            }
+            WsInMessage::InviteAccept { code } => {
+                Self::invite_accept(bus, user_id, code).await
+            }
+            WsInMessage::InviteRevoke { id } => {
+                Self::invite_revoke(bus, user_id, id).await
+            }
+            WsInMessage::BanCreate {
+                workspace,
+                user,
+                reason,
+                expires_at,
+            } => {
+                Self::ban_create(bus, user_id, workspace, user, reason, expires_at)
+                    .await
+            }
+            WsInMessage::BanRemove { workspace, user } => {
+                Self::ban_remove(bus, user_id, workspace, user).await
+            }
+            WsInMessage::VoiceJoin { room } => {
+                Self::voice_join(bus, user_id, room).await
+            }
+            WsInMessage::VoiceLeave { room } => {
+                Self::voice_leave(bus, user_id, room).await
+            }
+            WsInMessage::VoiceMute { room, muted } => {
+                Self::voice_mute(bus, user_id, room, muted).await
+            }
+            WsInMessage::VoiceDeaf { room, deafened } => {
+                Self::voice_deaf(bus, user_id, room, deafened).await
+            }
+            WsInMessage::ScreenShare { room, start } => {
+                Self::screen_share(bus, user_id, room, start).await
+            }
+            WsInMessage::AiList { room } => {
+                Self::ai_list(bus, user_id, room).await
+            }
+            WsInMessage::AiUpsert { room, model } => {
+                Self::ai_upsert(bus, user_id, room, model).await
+            }
+            WsInMessage::AiDelete { room, agent_id } => {
+                Self::ai_delete(bus, user_id, room, agent_id).await
+            }
+            WsInMessage::AiStop { room } => {
+                Self::ai_stop(bus, user_id, room).await
+            }
+            WsInMessage::UserSummary { username } => {
+                Self::user_summary(bus, username).await
+            }
+            WsInMessage::Search {
+                q,
+                room,
+                limit,
+                offset,
+                ..
+            } => Self::search(bus, user_id, q, room, limit, offset).await,
+            WsInMessage::ConversationPin { room, pin } => {
+                Self::conversation_pin(bus, user_id, room, pin).await
+            }
+            WsInMessage::ConversationMute { room, mute } => {
+                Self::conversation_mute(bus, user_id, room, mute).await
+            }
+            WsInMessage::ConversationNotifyLevel {
+                room,
+                notify_level,
+            } => {
+                Self::conversation_notify_level(
+                    bus, user_id, room, notify_level,
+                )
+                .await
+            }
+            WsInMessage::ConversationList => {
+                Self::conversation_list(bus, user_id).await
+            }
+            WsInMessage::DmCreate { recipient } => {
+                Self::dm_create(bus, user_id, recipient).await
+            }
+            WsInMessage::DmClose { room } => {
+                Self::dm_close(bus, user_id, room).await
+            }
+            WsInMessage::DmList => Self::dm_list(bus, user_id).await,
+            WsInMessage::MessageMarkRead {
+                room,
+                message_ids,
+            } => {
+                Self::message_mark_read(bus, user_id, room, message_ids).await
+            }
+            WsInMessage::MessageGetReaders { message_id } => {
+                Self::message_get_readers(bus, user_id, message_id).await
+            }
+            WsInMessage::MessageStar {
+                room,
+                message,
+                star,
+            } => Self::message_star(bus, user_id, room, message, star).await,
+            WsInMessage::StarredList { room, limit } => {
+                Self::starred_list(bus, user_id, room, limit).await
+            }
+            WsInMessage::MessageForward {
+                source_message_id,
+                target_room,
+            } => {
+                Self::message_forward(bus, user_id, source_message_id, target_room)
+                    .await
+            }
+        }
+    }
+}
diff --git a/lib/channel/http/handler/notification.rs b/lib/channel/http/handler/notification.rs
new file mode 100644
index 0000000..6ee34f8
--- /dev/null
+++ b/lib/channel/http/handler/notification.rs
@@ -0,0 +1,77 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{UserInfo, notify};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn notification_mark_read(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let result = db::sqlx::query(
+            "UPDATE user_app_notify SET read_at = now(), updated_at = now() \
+             WHERE id = $1 AND \"user\" = $2 AND read_at IS NULL AND archived_at IS NULL",
+        )
+        .bind(id)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        if result.rows_affected() == 0 {
+            return Err(ChannelError::RoomNotFound);
+        }
+        let nr_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = notify::NotifyReadService {
+            id,
+            user: nr_user,
+            read_at: Utc::now(),
+        };
+        Ok(Some(WsOutEvent::NotifyRead { data }))
+    }
+
+    pub(super) async fn notification_mark_all_read(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        workspace_id: Option<Uuid>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        if let Some(wk) = workspace_id {
+            db::sqlx::query(
+                "UPDATE user_app_notify SET read_at = now(), updated_at = now() \
+                 WHERE \"user\" = $1 AND target_id = $2 AND read_at IS NULL",
+            )
+            .bind(user_id)
+            .bind(wk)
+            .execute(bus.inner.db.writer())
+            .await?;
+        } else {
+            db::sqlx::query(
+                "UPDATE user_app_notify SET read_at = now(), updated_at = now() \
+                 WHERE \"user\" = $1 AND read_at IS NULL",
+            )
+            .bind(user_id)
+            .execute(bus.inner.db.writer())
+            .await?;
+        }
+        Ok(None)
+    }
+
+    pub(super) async fn notification_archive(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        db::sqlx::query(
+            "UPDATE user_app_notify SET archived_at = now(), updated_at = now() \
+             WHERE id = $1 AND \"user\" = $2 AND archived_at IS NULL",
+        )
+        .bind(id)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        Ok(None)
+    }
+}
diff --git a/lib/channel/http/handler/pin.rs b/lib/channel/http/handler/pin.rs
new file mode 100644
index 0000000..0f916b2
--- /dev/null
+++ b/lib/channel/http/handler/pin.rs
@@ -0,0 +1,83 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, pin};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn pin_add(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        message: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        Self::ensure_message_in_room(bus, room, message).await?;
+        let seq = bus.inner.seq.seq(room).await?;
+        let result = db::sqlx::query(
+            "INSERT INTO room_pin (room, message, seq, pinned_by, created_at) \
+             VALUES ($1, $2, $3, $4, now()) \
+             ON CONFLICT DO NOTHING",
+        )
+        .bind(room)
+        .bind(message)
+        .bind(seq)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        if result.rows_affected() == 0 {
+            return Ok(None);
+        }
+        db::sqlx::query("UPDATE room_message SET pinned = true, updated_at = now() WHERE id = $1")
+            .bind(message)
+            .execute(bus.inner.db.writer())
+            .await?;
+        let pa_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let pinned_by = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = pin::PinAddedService {
+            room: pa_room,
+            message,
+            pinned_by,
+            pinned_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "pin.added", &data).await?;
+        Ok(Some(WsOutEvent::PinAdded { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn pin_remove(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        message: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        Self::ensure_message_in_room(bus, room, message).await?;
+        let result = db::sqlx::query(
+            "DELETE FROM room_pin WHERE room = $1 AND message = $2",
+        )
+        .bind(room)
+        .bind(message)
+        .execute(bus.inner.db.writer())
+        .await?;
+        if result.rows_affected() == 0 {
+            return Ok(None);
+        }
+        db::sqlx::query("UPDATE room_message SET pinned = false, updated_at = now() WHERE id = $1")
+            .bind(message)
+            .execute(bus.inner.db.writer())
+            .await?;
+        let pr_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let removed_by = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = pin::PinRemovedService {
+            room: pr_room,
+            message,
+            removed_by,
+            removed_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "pin.removed", &data).await?;
+        Ok(Some(WsOutEvent::PinRemoved { room: data.room.clone(), data }))
+    }
+}
diff --git a/lib/channel/http/handler/presence.rs b/lib/channel/http/handler/presence.rs
new file mode 100644
index 0000000..3ddfaab
--- /dev/null
+++ b/lib/channel/http/handler/presence.rs
@@ -0,0 +1,94 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, member, presence};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn dnd_update(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        do_not_disturb: Option<bool>,
+        dnd_start_hour: Option<i16>,
+        dnd_end_hour: Option<i16>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let do_not_disturb = do_not_disturb.unwrap_or(false);
+        let start_hour = dnd_start_hour.map(|h| h as i32);
+        let end_hour = dnd_end_hour.map(|h| h as i32);
+        let key = format!("dnd:{}:{}", user_id, room);
+        let dnd_data = serde_json::json!({
+            "do_not_disturb": do_not_disturb,
+            "dnd_start_hour": start_hour,
+            "dnd_end_hour": end_hour,
+        });
+        bus.inner.cache.set(&key, &dnd_data).await?;
+        let dnd_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let dnd_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = member::DndUpdatedService {
+            room: dnd_room,
+            user: dnd_user,
+            do_not_disturb,
+            dnd_start_hour: start_hour,
+            dnd_end_hour: end_hour,
+        };
+        bus.publish_room_event(room, "member.dnd_updated", &data).await?;
+        Ok(None)
+    }
+
+    pub(super) async fn presence_update(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        status: presence::UserPresenceStatus,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let pc_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = presence::PresenceChangedService {
+            user: pc_user,
+            project: None,
+            status,
+            last_seen_at: Some(Utc::now()),
+        };
+        let rooms = crate::rooms::user_rooms(
+            &bus.inner.db,
+            &bus.inner.cache,
+            &bus.inner.config,
+            user_id,
+        )
+        .await?;
+        for room in rooms {
+            bus.publish_room_event(room, "presence.changed", &data).await?;
+        }
+        Ok(Some(WsOutEvent::PresenceChanged { data }))
+    }
+
+    pub(super) async fn custom_status_update(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        emoji: Option<String>,
+        text: Option<String>,
+        expires_at: Option<chrono::DateTime<chrono::Utc>>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let cs_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = presence::CustomStatusUpdatedService {
+            user: cs_user,
+            emoji,
+            text,
+            expires_at,
+        };
+        let rooms = crate::rooms::user_rooms(
+            &bus.inner.db,
+            &bus.inner.cache,
+            &bus.inner.config,
+            user_id,
+        )
+        .await?;
+        for room in rooms {
+            bus.publish_room_event(room, "custom_status.updated", &data).await?;
+        }
+        Ok(Some(WsOutEvent::CustomStatusUpdated { data }))
+    }
+}
diff --git a/lib/channel/http/handler/reaction.rs b/lib/channel/http/handler/reaction.rs
new file mode 100644
index 0000000..786cd50
--- /dev/null
+++ b/lib/channel/http/handler/reaction.rs
@@ -0,0 +1,91 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, reaction};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn reaction_add(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        message: Uuid,
+        emoji: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        Self::ensure_message_in_room(bus, room, message).await?;
+        if emoji.is_empty() || emoji.len() > 100 {
+            return Err(ChannelError::Validation("invalid emoji".into()));
+        }
+        let seq = bus.inner.seq.seq(room).await?;
+        let result = db::sqlx::query(
+            "INSERT INTO room_reaction (message, \"user\", seq, reaction, created_at) \
+             VALUES ($1, $2, $3, $4, now()) \
+             ON CONFLICT DO NOTHING",
+        )
+        .bind(message)
+        .bind(user_id)
+        .bind(seq)
+        .bind(&emoji)
+        .execute(bus.inner.db.writer())
+        .await?;
+        if result.rows_affected() == 0 {
+            return Ok(None);
+        }
+        let user = bus
+            .lookup_user(user_id)
+            .await
+            .unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let rct_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let data = reaction::ReactionAddedService {
+            id: Uuid::now_v7(),
+            room: rct_room,
+            message,
+            user,
+            emoji,
+            created_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "reaction.added", &data).await?;
+        Ok(Some(WsOutEvent::ReactionAdded { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn reaction_remove(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        message: Uuid,
+        emoji: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        Self::ensure_message_in_room(bus, room, message).await?;
+        let result = db::sqlx::query(
+            "DELETE FROM room_reaction WHERE message = $1 AND \"user\" = $2 AND reaction = $3",
+        )
+        .bind(message)
+        .bind(user_id)
+        .bind(&emoji)
+        .execute(bus.inner.db.writer())
+        .await?;
+        if result.rows_affected() == 0 {
+            return Ok(None);
+        }
+        let user = bus
+            .lookup_user(user_id)
+            .await
+            .unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let rct_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let data = reaction::ReactionRemovedService {
+            id: Uuid::now_v7(),
+            room: rct_room,
+            message,
+            user,
+            emoji,
+            removed_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "reaction.removed", &data).await?;
+        Ok(Some(WsOutEvent::ReactionRemoved { room: data.room.clone(), data }))
+    }
+}
diff --git a/lib/channel/http/handler/room.rs b/lib/channel/http/handler/room.rs
new file mode 100644
index 0000000..a72518c
--- /dev/null
+++ b/lib/channel/http/handler/room.rs
@@ -0,0 +1,259 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, WorkspaceInfo, member, rooms};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::{MAX_ROOM_NAME_LEN};
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn room_get(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let row = db::sqlx::query_as::<_, model::room::RoomModel>(
+            "SELECT id, wk, parent, name, topic, room_type, position, \
+             is_private, is_archived, created_by, created_at, updated_at, deleted_at \
+             FROM room WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(room)
+        .fetch_one(bus.inner.db.reader())
+        .await?;
+        Ok(Some(WsOutEvent::Response {
+            request_id: Uuid::nil(),
+            data: serde_json::json!({
+                "id": row.id,
+                "wk": row.wk,
+                "name": row.name,
+                "topic": row.topic,
+                "room_type": row.room_type,
+                "is_private": row.is_private,
+                "is_archived": row.is_archived,
+                "parent": row.parent,
+                "created_by": row.created_by,
+                "created_at": row.created_at,
+            }),
+        }))
+    }
+
+    pub(super) async fn room_create(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        workspace: Uuid,
+        room_name: String,
+        public: bool,
+        category: Option<Uuid>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        if room_name.is_empty() || room_name.len() > MAX_ROOM_NAME_LEN {
+            return Err(ChannelError::Validation("invalid room name".into()));
+        }
+        Self::ensure_workspace_member(bus, user_id, workspace).await?;
+        let is_private = !public;
+        let row = db::sqlx::query_as::<_, model::room::RoomModel>(
+            "INSERT INTO room (wk, parent, name, room_type, is_private, created_by, created_at, updated_at) \
+             VALUES ($1, $2, $3, 'channel', $4, $5, now(), now()) \
+             RETURNING id, wk, parent, name, topic, room_type, position, \
+             is_private, is_archived, created_by, created_at, updated_at, deleted_at",
+        )
+        .bind(workspace)
+        .bind(category)
+        .bind(&room_name)
+        .bind(is_private)
+        .bind(user_id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        db::sqlx::query(
+            "INSERT INTO room_permission_overwrite \
+             (room, target_type, target_id, allow_permissions, deny_permissions, created_at, updated_at) \
+             VALUES ($1, 'user', $2, '', '', now(), now())",
+        )
+        .bind(row.id)
+        .bind(user_id)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let data = rooms::RoomCreatedService {
+            room: RoomInfo::from_model(&row),
+            workspace: bus.lookup_workspace(workspace).await.unwrap_or_else(|_| WorkspaceInfo::unknown(workspace)),
+            public,
+            category,
+            created_by: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+            created_at: row.created_at,
+        };
+        bus.publish_room_event(row.id, "room.created", &data).await?;
+        bus.room_changed(row.id).await?;
+        Ok(Some(WsOutEvent::RoomCreated { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn room_update(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        room_name: Option<String>,
+        public: Option<bool>,
+        category: Option<Uuid>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let old = db::sqlx::query_as::<_, model::room::RoomModel>(
+            "SELECT id, wk, parent, name, topic, room_type, position, \
+             is_private, is_archived, created_by, created_at, updated_at, deleted_at \
+             FROM room WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(room)
+        .fetch_one(bus.inner.db.reader())
+        .await?;
+        let new_name = room_name.unwrap_or(old.name.clone());
+        let new_private =
+            public.map(|p| !p).unwrap_or(old.is_private);
+        let new_category = category.or(old.parent);
+        let row = db::sqlx::query_as::<_, model::room::RoomModel>(
+            "UPDATE room SET name = $2, is_private = $3, parent = $4, updated_at = now() \
+             WHERE id = $1 AND deleted_at IS NULL \
+             RETURNING id, wk, parent, name, topic, room_type, position, \
+             is_private, is_archived, created_by, created_at, updated_at, deleted_at",
+        )
+        .bind(room)
+        .bind(&new_name)
+        .bind(new_private)
+        .bind(new_category)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let mut renamed = false;
+        if new_name != old.name {
+            let data = rooms::RoomRenamedService {
+                room: RoomInfo::from_model(&row),
+                workspace: bus.lookup_workspace(row.wk).await.unwrap_or_else(|_| WorkspaceInfo::unknown(row.wk)),
+                old_name: old.name.clone(),
+                new_name: new_name,
+                renamed_by: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+                renamed_at: Utc::now(),
+            };
+            bus.publish_room_event(room, "room.renamed", &data).await?;
+            renamed = true;
+        }
+        if new_private != old.is_private || new_category != old.parent {
+            let data = rooms::RoomSettingsUpdatedService {
+                room: RoomInfo::from_model(&row),
+                workspace: bus.lookup_workspace(row.wk).await.unwrap_or_else(|_| WorkspaceInfo::unknown(row.wk)),
+                slowmode_seconds: None,
+                nsfw: false,
+                default_auto_archive_duration: None,
+                updated_by: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+                updated_at: Utc::now(),
+            };
+            bus.publish_room_event(room, "room.settings_updated", &data).await?;
+        }
+        bus.room_changed(room).await?;
+        if renamed {
+            return Ok(Some(WsOutEvent::RoomRenamed {
+                room: RoomInfo::from_model(&row),
+                data: rooms::RoomRenamedService {
+                    room: RoomInfo::from_model(&row),
+                    workspace: bus.lookup_workspace(row.wk).await.unwrap_or_else(|_| WorkspaceInfo::unknown(row.wk)),
+                    old_name: old.name,
+                    new_name: row.name,
+                    renamed_by: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+                    renamed_at: Utc::now(),
+                },
+            }));
+        }
+        Ok(None)
+    }
+
+    pub(super) async fn room_delete(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let old = db::sqlx::query_as::<_, model::room::RoomModel>(
+            "SELECT id, wk, parent, name, topic, room_type, position, \
+             is_private, is_archived, created_by, created_at, updated_at, deleted_at \
+             FROM room WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(room)
+        .fetch_one(bus.inner.db.reader())
+        .await?;
+        if old.created_by != user_id {
+            return Err(ChannelError::AccessDenied);
+        }
+        let row = db::sqlx::query_as::<_, model::room::RoomModel>(
+            "UPDATE room SET deleted_at = now(), updated_at = now() \
+             WHERE id = $1 AND deleted_at IS NULL \
+             RETURNING id, wk, parent, name, topic, room_type, position, \
+             is_private, is_archived, created_by, created_at, updated_at, deleted_at",
+        )
+        .bind(room)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let data = rooms::RoomDeletedService {
+            room: RoomInfo::from_model(&row),
+            workspace: bus.lookup_workspace(row.wk).await.unwrap_or_else(|_| WorkspaceInfo::unknown(row.wk)),
+            deleted_by: bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id)),
+            deleted_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "room.deleted", &data).await?;
+        bus.room_changed(room).await?;
+        Ok(Some(WsOutEvent::RoomDeleted { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn access_grant(
+        bus: &ChannelBus,
+        _user_id: Uuid,
+        room: Uuid,
+        target_user: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        db::sqlx::query(
+            "INSERT INTO room_permission_overwrite \
+             (room, target_type, target_id, allow_permissions, deny_permissions, created_at, updated_at) \
+             SELECT $1, 'user', $2, '', '', now(), now() \
+             WHERE NOT EXISTS (SELECT 1 FROM room_permission_overwrite WHERE room = $1 AND target_type = 'user' AND target_id = $2)",
+        )
+        .bind(room)
+        .bind(target_user)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let mj_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let mj_user = bus.lookup_user(target_user).await.unwrap_or_else(|_| UserInfo::unknown(target_user));
+        let data = member::MemberJoinedService {
+            room: mj_room,
+            user: mj_user,
+            project_role: None,
+            joined_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "member.joined", &data).await?;
+        bus.room_changed(room).await?;
+        Ok(Some(WsOutEvent::MemberJoined { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn access_revoke(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        target_user: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        db::sqlx::query(
+            "DELETE FROM room_permission_overwrite \
+             WHERE room = $1 AND target_type = 'user' AND target_id = $2",
+        )
+        .bind(room)
+        .bind(target_user)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let mr_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let mr_target = bus.lookup_user(target_user).await.unwrap_or_else(|_| UserInfo::unknown(target_user));
+        let mr_remover = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = member::MemberRemovedService {
+            room: mr_room,
+            user: mr_target,
+            removed_by: mr_remover,
+            removed_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "member.removed", &data).await?;
+        bus.room_changed(room).await?;
+        Ok(Some(WsOutEvent::MemberRemoved { room: data.room.clone(), data }))
+    }
+}
diff --git a/lib/channel/http/handler/search.rs b/lib/channel/http/handler/search.rs
new file mode 100644
index 0000000..64cb239
--- /dev/null
+++ b/lib/channel/http/handler/search.rs
@@ -0,0 +1,90 @@
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo};
+use crate::{
+    ChannelBus, ChannelError, ChannelResult,
+    search::{SearchEngine, SearchQuery},
+};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn search(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        q: String,
+        room: Option<Uuid>,
+        limit: Option<u64>,
+        offset: Option<u64>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        if let Some(room_id) = room {
+            Self::ensure_room_access(bus, user_id, room_id).await?;
+        } else {
+            return Err(ChannelError::Validation(
+                "room is required for websocket search".to_string(),
+            ));
+        }
+        let engine = SearchEngine::new(bus.inner.db.clone());
+        let result = engine
+            .search(SearchQuery {
+                query: q.clone(),
+                room_id: room,
+                user_id: None,
+                limit: limit.unwrap_or(50),
+                offset: offset.unwrap_or(0),
+            })
+            .await?;
+
+        let author_ids: Vec<Uuid> = result.hits.iter().map(|h| h.sender_id).collect();
+        let message_ids: Vec<Uuid> = result.hits.iter().map(|h| h.message_id).collect();
+        let user_map = bus.lookup_users(&author_ids).await.unwrap_or_default();
+        let reactions = Self::reaction_groups_for_messages(bus, user_id, &message_ids)
+            .await
+            .unwrap_or_default();
+
+        let search_room = match room {
+            Some(r) => Some(bus.lookup_room(r).await.unwrap_or_else(|_| RoomInfo::unknown(r))),
+            None => None,
+        };
+        let search_msg_room = search_room.clone().unwrap_or_else(|| RoomInfo::unknown(room.unwrap_or_default()));
+        let data = crate::event::search::SearchResultService {
+            q,
+            room: search_room,
+            messages: result
+                .hits
+                .into_iter()
+                .map(|h| {
+                    let sender = user_map
+                        .get(&h.sender_id)
+                        .cloned()
+                        .unwrap_or_else(|| UserInfo::unknown(h.sender_id));
+                    crate::event::search::SearchMessageHitService {
+                    message: crate::event::message::MessageNewService {
+                        id: h.message_id,
+                        seq: 0,
+                        room: search_msg_room.clone(),
+                        sender_type: "user".to_string(),
+                        sender,
+                        thread: None,
+                        in_reply_to: None,
+                        content: h.content.clone(),
+                        content_type: "text".to_string(),
+                        pinned: false,
+                        system_type: None,
+                        metadata: serde_json::Value::Null,
+                        thinking_content: None,
+                        thinking_is_chunked: None,
+                        send_at: h.send_at,
+                        reactions: reactions.get(&h.message_id).cloned().unwrap_or_default(),
+                    },
+                    highlighted_content: h.highlighted,
+                }})
+                .collect(),
+            total: result.total as i64,
+            took_ms: 0,
+        };
+
+        Ok(Some(WsOutEvent::SearchResult { data }))
+    }
+}
diff --git a/lib/channel/http/handler/star.rs b/lib/channel/http/handler/star.rs
new file mode 100644
index 0000000..1df491d
--- /dev/null
+++ b/lib/channel/http/handler/star.rs
@@ -0,0 +1,157 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, star};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn message_star(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        message: Uuid,
+        do_star: bool,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        Self::ensure_message_in_room(bus, room, message).await?;
+
+        let room_info =
+            bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let user_info =
+            bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+        if do_star {
+            let result = db::sqlx::query(
+                "INSERT INTO message_star (message, room, \"user\", created_at) \
+                 VALUES ($1, $2, $3, now()) ON CONFLICT (message, \"user\") DO NOTHING",
+            )
+            .bind(message)
+            .bind(room)
+            .bind(user_id)
+            .execute(bus.inner.db.writer())
+            .await?;
+
+            if result.rows_affected() == 0 {
+                return Ok(None);
+            }
+
+            let seq_row: Option<(i64,)> = db::sqlx::query_as(
+                "SELECT seq FROM room_message WHERE id = $1",
+            )
+            .bind(message)
+            .fetch_optional(bus.inner.db.reader())
+            .await?;
+
+            let data = star::MessageStarredService {
+                room: room_info.clone(),
+                message_id: message,
+                message_seq: seq_row.map(|r| r.0).unwrap_or(0),
+                starred_by: user_info,
+                starred_at: Utc::now(),
+            };
+            bus.emit_to_user(user_id, "message.starred", &data).await?;
+            Ok(Some(WsOutEvent::MessageStarred {
+                room: room_info,
+                data,
+            }))
+        } else {
+            let result = db::sqlx::query(
+                "DELETE FROM message_star WHERE message = $1 AND \"user\" = $2",
+            )
+            .bind(message)
+            .bind(user_id)
+            .execute(bus.inner.db.writer())
+            .await?;
+
+            if result.rows_affected() == 0 {
+                return Ok(None);
+            }
+
+            let data = star::MessageUnstarredService {
+                room: room_info.clone(),
+                message_id: message,
+                unstarred_by: user_info,
+                unstarred_at: Utc::now(),
+            };
+            bus.emit_to_user(user_id, "message.unstarred", &data).await?;
+            Ok(Some(WsOutEvent::MessageUnstarred {
+                room: room_info,
+                data,
+            }))
+        }
+    }
+    pub(super) async fn starred_list(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Option<Uuid>,
+        limit: Option<u64>,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let limit = limit.unwrap_or(50).min(100) as i64;
+
+        let rows = if let Some(room_id) = room {
+            Self::ensure_room_access(bus, user_id, room_id).await?;
+            db::sqlx::query_as::<_, (Uuid, Uuid, i64, String, String, Uuid, chrono::DateTime<Utc>, chrono::DateTime<Utc>)>(
+                "SELECT ms.id, rm.id, rm.seq, rm.content, rm.content_type, rm.author, ms.created_at, rm.created_at \
+                 FROM message_star ms \
+                 JOIN room_message rm ON rm.id = ms.message \
+                 WHERE ms.\"user\" = $1 AND ms.room = $2 AND rm.deleted_at IS NULL \
+                 ORDER BY ms.created_at DESC LIMIT $3",
+            )
+            .bind(user_id)
+            .bind(room_id)
+            .bind(limit)
+            .fetch_all(bus.inner.db.reader())
+            .await?
+        } else {
+            db::sqlx::query_as::<_, (Uuid, Uuid, i64, String, String, Uuid, chrono::DateTime<Utc>, chrono::DateTime<Utc>)>(
+                "SELECT ms.id, rm.id, rm.seq, rm.content, rm.content_type, rm.author, ms.created_at, rm.created_at \
+                 FROM message_star ms \
+                 JOIN room_message rm ON rm.id = ms.message \
+                 WHERE ms.\"user\" = $1 AND rm.deleted_at IS NULL \
+                 ORDER BY ms.created_at DESC LIMIT $2",
+            )
+            .bind(user_id)
+            .bind(limit)
+            .fetch_all(bus.inner.db.reader())
+            .await?
+        };
+
+        let author_ids: Vec<Uuid> = rows.iter().map(|r| r.5).collect();
+        let user_map = bus.lookup_users(&author_ids).await.unwrap_or_default();
+
+        let mut entries = Vec::with_capacity(rows.len());
+        for (_star_id, msg_id, seq, content, content_type, author_id, starred_at, sent_at) in rows {
+            let msg_room_row: Option<(Uuid,)> = db::sqlx::query_as(
+                "SELECT room FROM room_message WHERE id = $1",
+            )
+            .bind(msg_id)
+            .fetch_optional(bus.inner.db.reader())
+            .await?;
+            let msg_room_id = msg_room_row.map(|r| r.0).unwrap_or(Uuid::nil());
+            let room_info = bus
+                .lookup_room(msg_room_id)
+                .await
+                .unwrap_or_else(|_| RoomInfo::unknown(msg_room_id));
+            let sender = user_map
+                .get(&author_id)
+                .cloned()
+                .unwrap_or_else(|| UserInfo::unknown(author_id));
+
+            entries.push(star::StarredMessageEntry {
+                message_id: msg_id,
+                room: room_info,
+                seq,
+                content,
+                content_type,
+                sender,
+                starred_at,
+                sent_at,
+            });
+        }
+
+        Ok(Some(WsOutEvent::StarredList { data: entries }))
+    }
+}
diff --git a/lib/channel/http/handler/subscription.rs b/lib/channel/http/handler/subscription.rs
new file mode 100644
index 0000000..c5a64ca
--- /dev/null
+++ b/lib/channel/http/handler/subscription.rs
@@ -0,0 +1,143 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, member};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn subscribe(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        _room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        bus.refresh_user(user_id).await?;
+        Ok(None)
+    }
+
+    pub(super) async fn unsubscribe(
+        _bus: &ChannelBus,
+        _user_id: Uuid,
+        _room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Ok(None)
+    }
+
+    pub(super) async fn typing(
+        bus: &ChannelBus,
+        room: Uuid,
+        user_id: Uuid,
+        action: &str,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+
+        let key = (room, user_id);
+
+        if action == "start" {
+            let ty_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+            let ty_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+            let already_typing = bus.inner.typing_states.contains_key(&key);
+            if let Some((_, (_, _, old_cancel))) = bus.inner.typing_states.remove(&key) {
+                old_cancel.cancel();
+            }
+
+            let cancel = tokio_util::sync::CancellationToken::new();
+            let cancel_clone = cancel.clone();
+            let bus_clone = bus.clone();
+            let user_clone = ty_user.clone();
+            let room_clone = ty_room.clone();
+            bus.inner.typing_states.insert(key, (ty_user.clone(), ty_room.clone(), cancel));
+            tokio::spawn(async move {
+                tokio::time::sleep(std::time::Duration::from_secs(10)).await;
+                if cancel_clone.is_cancelled() {
+                    return;
+                }
+                bus_clone.inner.typing_states.remove(&(room_clone.id, user_clone.id));
+                let room_id = room_clone.id;
+                let stop_data = member::TypingStopService {
+                    room: room_clone,
+                    user: user_clone,
+                    sender_type: "user".to_string(),
+                    stopped_at: Utc::now(),
+                };
+                let _ = bus_clone.publish_room_event(room_id, "typing.stop", &stop_data).await;
+            });
+            if !already_typing {
+                let data = member::TypingStartService {
+                    room: ty_room,
+                    user: ty_user,
+                    sender_type: "user".to_string(),
+                    started_at: Utc::now(),
+                };
+                bus.publish_room_event(room, "typing.start", &data).await?;
+                return Ok(Some(WsOutEvent::TypingStart { room: data.room.clone(), data }));
+            }
+            Ok(None)
+        } else {
+            if let Some((_, (_, _, cancel))) = bus.inner.typing_states.remove(&key) {
+                cancel.cancel();
+            }
+
+            let ty_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+            let ty_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+
+            let data = member::TypingStopService {
+                room: ty_room,
+                user: ty_user,
+                sender_type: "user".to_string(),
+                stopped_at: Utc::now(),
+            };
+            bus.publish_room_event(room, "typing.stop", &data).await?;
+            Ok(Some(WsOutEvent::TypingStop { room: data.room.clone(), data }))
+        }
+    }
+
+    pub(super) async fn read_receipt(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        last_read_seq: i64,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        bus.inner
+            .reconnect
+            .save_client_state(user_id, room, last_read_seq)
+            .await?;
+        db::sqlx::query(
+            "INSERT INTO user_room_state (\"user\", room, last_read_seq, last_read_at, updated_at) \
+             VALUES ($1, $2, $3, now(), now()) \
+             ON CONFLICT (\"user\", room) DO UPDATE \
+             SET last_read_seq = GREATEST(user_room_state.last_read_seq, $3), \
+                 last_read_at = now(), updated_at = now()",
+        )
+        .bind(user_id)
+        .bind(room)
+        .bind(last_read_seq)
+        .execute(bus.inner.db.writer())
+        .await?;
+        let rr_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let rr_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = member::ReadReceiptService {
+            room: rr_room.clone(),
+            user: rr_user,
+            last_read_seq,
+            updated_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "member.read_receipt", &data)
+            .await?;
+        Ok(Some(WsOutEvent::ReadReceipt {
+            room: rr_room,
+            data,
+        }))
+    }
+
+    pub(super) async fn csrf_token(
+        bus: &ChannelBus,
+        user_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let token = bus.inner.csrf.generate_token(user_id).await?;
+        Ok(Some(WsOutEvent::CsrfToken { token }))
+    }
+}
diff --git a/lib/channel/http/handler/thread.rs b/lib/channel/http/handler/thread.rs
new file mode 100644
index 0000000..95c7d00
--- /dev/null
+++ b/lib/channel/http/handler/thread.rs
@@ -0,0 +1,121 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, thread};
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn thread_create(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        parent: i64,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        // Look up the message UUID from seq + room
+        let parent_id: Option<(Uuid,)> = db::sqlx::query_as(
+            "SELECT id FROM room_message WHERE room = $1 AND seq = $2 AND deleted_at IS NULL",
+        )
+        .bind(room)
+        .bind(parent)
+        .fetch_optional(bus.inner.db.reader())
+        .await?;
+        let parent_msg_id = parent_id.ok_or(ChannelError::RoomNotFound)?.0;
+        let seq = bus.inner.seq.seq(room).await?;
+        let row = db::sqlx::query_as::<_, model::room::RoomThreadModel>(
+            "INSERT INTO room_thread (room, seq, starter_message, title, created_by, created_at, updated_at) \
+             VALUES ($1, $2, $3, '', $4, now(), now()) \
+             RETURNING id, room, seq, starter_message, title, created_by, archived, locked, \
+             last_message_at, created_at, updated_at, archived_at",
+        )
+        .bind(room)
+        .bind(seq)
+        .bind(parent_msg_id)  // UUID of the starter message
+        .bind(user_id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let tc_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let created_by = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = thread::ThreadCreatedService {
+            id: row.id,
+            room: tc_room,
+            parent,
+            created_by,
+            participants: serde_json::Value::Null,
+            created_at: row.created_at,
+        };
+        bus.publish_room_event(room, "thread.created", &data).await?;
+        Ok(Some(WsOutEvent::ThreadCreated { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn thread_resolve(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        thread_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let existing: (Uuid,) = db::sqlx::query_as(
+            "SELECT room FROM room_thread WHERE id = $1",
+        )
+        .bind(thread_id)
+        .fetch_optional(bus.inner.db.reader())
+        .await?
+        .ok_or(ChannelError::RoomNotFound)?;
+        Self::ensure_room_access(bus, user_id, existing.0).await?;
+        let row = db::sqlx::query_as::<_, model::room::RoomThreadModel>(
+            "UPDATE room_thread SET locked = true, updated_at = now() \
+             WHERE id = $1 \
+             RETURNING id, room, seq, starter_message, title, created_by, archived, locked, \
+             last_message_at, created_at, updated_at, archived_at",
+        )
+        .bind(thread_id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let tr_room = bus.lookup_room(row.room).await.unwrap_or_else(|_| RoomInfo::unknown(row.room));
+        let resolved_by = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = thread::ThreadResolvedService {
+            id: row.id,
+            room: tr_room,
+            resolved_by,
+            resolved_at: Utc::now(),
+        };
+        bus.publish_room_event(row.room, "thread.resolved", &data).await?;
+        Ok(Some(WsOutEvent::ThreadResolved { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn thread_archive(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        thread_id: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let existing: (Uuid,) = db::sqlx::query_as(
+            "SELECT room FROM room_thread WHERE id = $1",
+        )
+        .bind(thread_id)
+        .fetch_optional(bus.inner.db.reader())
+        .await?
+        .ok_or(ChannelError::RoomNotFound)?;
+        Self::ensure_room_access(bus, user_id, existing.0).await?;
+        let row = db::sqlx::query_as::<_, model::room::RoomThreadModel>(
+            "UPDATE room_thread SET archived = true, archived_at = now(), updated_at = now() \
+             WHERE id = $1 \
+             RETURNING id, room, seq, starter_message, title, created_by, archived, locked, \
+             last_message_at, created_at, updated_at, archived_at",
+        )
+        .bind(thread_id)
+        .fetch_one(bus.inner.db.writer())
+        .await?;
+        let ta_room = bus.lookup_room(row.room).await.unwrap_or_else(|_| RoomInfo::unknown(row.room));
+        let archived_by = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = thread::ThreadArchivedService {
+            id: row.id,
+            room: ta_room,
+            archived_by,
+            archived_at: Utc::now(),
+        };
+        bus.publish_room_event(row.room, "thread.archived", &data).await?;
+        Ok(Some(WsOutEvent::ThreadArchived { room: data.room.clone(), data }))
+    }
+}
diff --git a/lib/channel/http/handler/user.rs b/lib/channel/http/handler/user.rs
new file mode 100644
index 0000000..37068ab
--- /dev/null
+++ b/lib/channel/http/handler/user.rs
@@ -0,0 +1,35 @@
+use uuid::Uuid;
+
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn user_summary(
+        bus: &ChannelBus,
+        username: String,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        let user = db::sqlx::query_as::<_, model::users::UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, \
+             allow_use, can_search, last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE username = $1",
+        )
+        .bind(&username)
+        .fetch_one(bus.inner.db.reader())
+        .await
+        .map_err(|e| match e {
+            db::sqlx::Error::RowNotFound => ChannelError::RoomNotFound,
+            other => ChannelError::Database(other),
+        })?;
+        Ok(Some(WsOutEvent::Response {
+            request_id: Uuid::nil(),
+            data: serde_json::json!({
+                "id": user.id,
+                "username": user.username,
+                "display_name": user.display_name,
+                "avatar_url": user.avatar_url,
+            }),
+        }))
+    }
+}
diff --git a/lib/channel/http/handler/voice.rs b/lib/channel/http/handler/voice.rs
new file mode 100644
index 0000000..403f402
--- /dev/null
+++ b/lib/channel/http/handler/voice.rs
@@ -0,0 +1,97 @@
+use chrono::Utc;
+use uuid::Uuid;
+
+use crate::event::{RoomInfo, UserInfo, voice};
+use crate::{ChannelBus, ChannelResult};
+
+use super::WsOutEvent;
+use super::WsHandler;
+
+impl WsHandler {
+    pub(super) async fn voice_join(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let vj_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let vj_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = voice::VoiceChannelJoinedService {
+            room: vj_room,
+            workspace: None,
+            user: vj_user,
+            muted: false,
+            deafened: false,
+            video: false,
+            joined_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "voice.channel_joined", &data).await?;
+        Ok(Some(WsOutEvent::VoiceChannelJoined { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn voice_leave(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        let vl_room = bus.lookup_room(room).await.unwrap_or_else(|_| RoomInfo::unknown(room));
+        let vl_user = bus.lookup_user(user_id).await.unwrap_or_else(|_| UserInfo::unknown(user_id));
+        let data = voice::VoiceChannelLeftService {
+            room: vl_room,
+            workspace: None,
+            user: vl_user,
+            left_at: Utc::now(),
+        };
+        bus.publish_room_event(room, "voice.channel_left", &data).await?;
+        Ok(Some(WsOutEvent::VoiceChannelLeft { room: data.room.clone(), data }))
+    }
+
+    pub(super) async fn voice_mute(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        muted: bool,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        bus.publish_room_event(
+            room,
+            "voice.mute_updated",
+            &serde_json::json!({"user_id": user_id, "muted": muted}),
+        )
+        .await?;
+        Ok(None)
+    }
+
+    pub(super) async fn voice_deaf(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        deafened: bool,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        bus.publish_room_event(
+            room,
+            "voice.deaf_updated",
+            &serde_json::json!({"user_id": user_id, "deafened": deafened}),
+        )
+        .await?;
+        Ok(None)
+    }
+
+    pub(super) async fn screen_share(
+        bus: &ChannelBus,
+        user_id: Uuid,
+        room: Uuid,
+        start: bool,
+    ) -> ChannelResult<Option<WsOutEvent>> {
+        Self::ensure_room_access(bus, user_id, room).await?;
+        bus.publish_room_event(
+            room,
+            "voice.screen_share",
+            &serde_json::json!({"user_id": user_id, "start": start}),
+        )
+        .await?;
+        Ok(None)
+    }
+}
diff --git a/lib/channel/http/mod.rs b/lib/channel/http/mod.rs
new file mode 100644
index 0000000..1fd8392
--- /dev/null
+++ b/lib/channel/http/mod.rs
@@ -0,0 +1,10 @@
+pub mod handler;
+pub mod out_event;
+pub mod session;
+pub mod types;
+pub mod ws;
+
+pub use handler::WsHandler;
+pub use out_event::{WsError, WsOutEvent};
+pub use session::WsUserCtx;
+pub use types::{WS_PROTOCOL_VERSION, WsInMessage};
diff --git a/lib/channel/http/out_event.rs b/lib/channel/http/out_event.rs
new file mode 100644
index 0000000..4b9bdcf
--- /dev/null
+++ b/lib/channel/http/out_event.rs
@@ -0,0 +1,287 @@
+use serde::Serialize;
+use uuid::Uuid;
+
+use crate::event::{
+    RoomInfo, WorkspaceInfo,
+    ai, attachment, ban, category, conversation, dm, draft, forward, invite,
+    member, message, message_read, notify, pin, presence, reaction, rooms,
+    search, star, thread, voice, workspace,
+};
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum WsOutEvent {
+    Pong {
+        protocol_version: u32,
+    },
+    Error(WsError),
+    CsrfToken {
+        token: String,
+    },
+    RoomCreated {
+        room: RoomInfo,
+        data: rooms::RoomCreatedService,
+    },
+    RoomDeleted {
+        room: RoomInfo,
+        data: rooms::RoomDeletedService,
+    },
+    RoomRenamed {
+        room: RoomInfo,
+        data: rooms::RoomRenamedService,
+    },
+    RoomTopicUpdated {
+        room: RoomInfo,
+        data: rooms::RoomTopicUpdatedService,
+    },
+    RoomSettingsUpdated {
+        room: RoomInfo,
+        data: rooms::RoomSettingsUpdatedService,
+    },
+    RoomMoved {
+        room: RoomInfo,
+        data: rooms::RoomMovedService,
+    },
+    MessageNew {
+        room: RoomInfo,
+        data: message::MessageNewService,
+    },
+    MessageEdited {
+        room: RoomInfo,
+        data: message::MessageEditedService,
+    },
+    MessageRevoked {
+        room: RoomInfo,
+        data: message::MessageRevokedService,
+    },
+    MessageStreamStart {
+        room: RoomInfo,
+        data: message::MessageStreamStartService,
+    },
+    MessageStreamChunk {
+        room: RoomInfo,
+        data: message::MessageStreamChunkService,
+    },
+    MessageStreamDone {
+        room: RoomInfo,
+        data: message::MessageStreamDoneService,
+    },
+    MessageList {
+        room: RoomInfo,
+        data: message::MessageListService,
+    },
+    MemberJoined {
+        room: RoomInfo,
+        data: member::MemberJoinedService,
+    },
+    MemberRemoved {
+        room: RoomInfo,
+        data: member::MemberRemovedService,
+    },
+    ReadReceipt {
+        room: RoomInfo,
+        data: member::ReadReceiptService,
+    },
+    TypingStart {
+        room: RoomInfo,
+        data: member::TypingStartService,
+    },
+    TypingStop {
+        room: RoomInfo,
+        data: member::TypingStopService,
+    },
+    ReactionAdded {
+        room: RoomInfo,
+        data: reaction::ReactionAddedService,
+    },
+    ReactionRemoved {
+        room: RoomInfo,
+        data: reaction::ReactionRemovedService,
+    },
+    ReactionBatchUpdated {
+        room: RoomInfo,
+        data: reaction::ReactionBatchUpdatedService,
+    },
+    ThreadCreated {
+        room: RoomInfo,
+        data: thread::ThreadCreatedService,
+    },
+    ThreadUpdated {
+        room: RoomInfo,
+        data: thread::ThreadUpdatedService,
+    },
+    ThreadResolved {
+        room: RoomInfo,
+        data: thread::ThreadResolvedService,
+    },
+    ThreadArchived {
+        room: RoomInfo,
+        data: thread::ThreadArchivedService,
+    },
+    CategoryCreated {
+        workspace: WorkspaceInfo,
+        data: category::CategoryCreatedService,
+    },
+    CategoryUpdated {
+        workspace: WorkspaceInfo,
+        data: category::CategoryUpdatedService,
+    },
+    CategoryDeleted {
+        workspace: WorkspaceInfo,
+        data: category::CategoryDeletedService,
+    },
+    PinAdded {
+        room: RoomInfo,
+        data: pin::PinAddedService,
+    },
+    PinRemoved {
+        room: RoomInfo,
+        data: pin::PinRemovedService,
+    },
+    WorkspaceRoomCreated {
+        workspace: WorkspaceInfo,
+        data: workspace::WorkspaceRoomCreatedService,
+    },
+    WorkspaceRoomDeleted {
+        workspace: WorkspaceInfo,
+        data: workspace::WorkspaceRoomDeletedService,
+    },
+    DraftSaved {
+        room: RoomInfo,
+        data: draft::DraftSavedService,
+    },
+    DraftCleared {
+        room: RoomInfo,
+        data: draft::DraftClearedService,
+    },
+    SearchResult {
+        data: search::SearchResultService,
+    },
+    NotifyCreated {
+        data: notify::NotifyCreatedService,
+    },
+    NotifyRead {
+        data: notify::NotifyReadService,
+    },
+    PresenceChanged {
+        data: presence::PresenceChangedService,
+    },
+    CustomStatusUpdated {
+        data: presence::CustomStatusUpdatedService,
+    },
+    InviteCreated {
+        data: invite::InviteCreatedService,
+    },
+    InviteAccepted {
+        data: invite::InviteAcceptedService,
+    },
+    AttachmentUploaded {
+        room: RoomInfo,
+        data: attachment::AttachmentUploadedService,
+    },
+    UserBanned {
+        data: ban::BannedService,
+    },
+    UserUnbanned {
+        data: ban::UnbannedService,
+    },
+    AiAgentJoined {
+        room: RoomInfo,
+        data: ai::AiAgentJoinedService,
+    },
+    AiAgentLeft {
+        room: RoomInfo,
+        data: ai::AiAgentLeftService,
+    },
+    AiAgentList {
+        room: RoomInfo,
+        data: ai::RoomAiListService,
+    },
+    AiAgentStatusChanged {
+        room: RoomInfo,
+        data: ai::AiAgentStatusChangedService,
+    },
+    VoiceChannelJoined {
+        room: RoomInfo,
+        data: voice::VoiceChannelJoinedService,
+    },
+    VoiceChannelLeft {
+        room: RoomInfo,
+        data: voice::VoiceChannelLeftService,
+    },
+    ConversationPinned {
+        room: RoomInfo,
+        data: conversation::ConversationPinnedService,
+    },
+    ConversationUnpinned {
+        room: RoomInfo,
+        data: conversation::ConversationUnpinnedService,
+    },
+    ConversationMuted {
+        room: RoomInfo,
+        data: conversation::ConversationMutedService,
+    },
+    ConversationUnmuted {
+        room: RoomInfo,
+        data: conversation::ConversationUnmutedService,
+    },
+    ConversationUnreadUpdated {
+        room: RoomInfo,
+        data: conversation::ConversationUnreadUpdatedService,
+    },
+    ConversationList {
+        data: Vec<conversation::ConversationSummary>,
+    },
+    DmCreated {
+        room: RoomInfo,
+        data: dm::DmCreatedService,
+    },
+    DmClosed {
+        room: RoomInfo,
+        data: dm::DmClosedService,
+    },
+    DmReopened {
+        room: RoomInfo,
+        data: dm::DmReopenedService,
+    },
+    DmList {
+        data: Vec<dm::DmCreatedService>,
+    },
+    MessageRead {
+        room: RoomInfo,
+        data: message_read::MessageReadService,
+    },
+    MessageReadBatch {
+        room: RoomInfo,
+        data: message_read::MessageReadBatchService,
+    },
+    MessageReaders {
+        data: message_read::MessageReadersService,
+    },
+    MessageStarred {
+        room: RoomInfo,
+        data: star::MessageStarredService,
+    },
+    MessageUnstarred {
+        room: RoomInfo,
+        data: star::MessageUnstarredService,
+    },
+    StarredList {
+        data: Vec<star::StarredMessageEntry>,
+    },
+    MessageForwarded {
+        room: RoomInfo,
+        data: forward::MessageForwardedService,
+    },
+    Response {
+        request_id: Uuid,
+        data: serde_json::Value,
+    },
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct WsError {
+    pub code: i32,
+    pub error: String,
+    pub message: String,
+}
diff --git a/lib/channel/http/session.rs b/lib/channel/http/session.rs
new file mode 100644
index 0000000..0313e51
--- /dev/null
+++ b/lib/channel/http/session.rs
@@ -0,0 +1,22 @@
+use uuid::Uuid;
+
+use crate::token::ChannelTokenContext;
+
+#[derive(Clone)]
+pub struct WsUserCtx {
+    pub user_id: Uuid,
+    pub device_id: String,
+    pub client_id: String,
+    pub display_name: String,
+}
+
+impl From<ChannelTokenContext> for WsUserCtx {
+    fn from(ctx: ChannelTokenContext) -> Self {
+        Self {
+            user_id: ctx.user_id,
+            device_id: ctx.device_id,
+            client_id: ctx.client_id,
+            display_name: ctx.user_id.to_string(),
+        }
+    }
+}
diff --git a/lib/channel/http/types.rs b/lib/channel/http/types.rs
new file mode 100644
index 0000000..aa6b56b
--- /dev/null
+++ b/lib/channel/http/types.rs
@@ -0,0 +1,329 @@
+pub const WS_PROTOCOL_VERSION: u32 = 1;
+
+use chrono::{DateTime, Utc};
+use serde::Deserialize;
+use uuid::Uuid;
+
+use crate::event::presence::UserPresenceStatus;
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum WsInMessage {
+    Ping,
+    Subscribe {
+        room: Uuid,
+    },
+    Unsubscribe {
+        room: Uuid,
+    },
+    TypingStart {
+        room: Uuid,
+    },
+    TypingStop {
+        room: Uuid,
+    },
+    ReadReceipt {
+        room: Uuid,
+        last_read_seq: i64,
+    },
+    MessageList {
+        room: Uuid,
+        before_seq: Option<i64>,
+        after_seq: Option<i64>,
+        limit: Option<u64>,
+    },
+    MessageAround {
+        room: Uuid,
+        seq: i64,
+        limit: Option<u64>,
+    },
+    MessageCreate {
+        room: Uuid,
+        content: String,
+        content_type: Option<String>,
+        thread: Option<Uuid>,
+        in_reply_to: Option<Uuid>,
+    },
+    MessageUpdate {
+        message: Uuid,
+        content: String,
+    },
+    MessageRevoke {
+        message: Uuid,
+    },
+    RoomGet {
+        room: Uuid,
+    },
+    RoomCreate {
+        workspace: Uuid,
+        room_name: String,
+        public: bool,
+        category: Option<Uuid>,
+    },
+    RoomUpdate {
+        room: Uuid,
+        room_name: Option<String>,
+        public: Option<bool>,
+        category: Option<Uuid>,
+    },
+    RoomDelete {
+        room: Uuid,
+    },
+    CategoryCreate {
+        workspace: Uuid,
+        name: String,
+        position: Option<i32>,
+    },
+    CategoryUpdate {
+        id: Uuid,
+        name: Option<String>,
+        position: Option<i32>,
+    },
+    CategoryDelete {
+        id: Uuid,
+    },
+    AccessGrant {
+        room: Uuid,
+        user: Uuid,
+    },
+    AccessRevoke {
+        room: Uuid,
+        user: Uuid,
+    },
+    StateSetReadSeq {
+        room: Uuid,
+        last_read_seq: i64,
+    },
+    MissedMessages {
+        room: Uuid,
+        after_seq: i64,
+        limit: Option<i64>,
+    },
+    CsrfToken,
+    StateUpdateDnd {
+        room: Uuid,
+        do_not_disturb: Option<bool>,
+        dnd_start_hour: Option<i16>,
+        dnd_end_hour: Option<i16>,
+    },
+    ReactionAdd {
+        room: Uuid,
+        message: Uuid,
+        emoji: String,
+    },
+    ReactionRemove {
+        room: Uuid,
+        message: Uuid,
+        emoji: String,
+    },
+    ThreadCreate {
+        room: Uuid,
+        parent: i64,
+    },
+    ThreadResolve {
+        thread_id: Uuid,
+    },
+    ThreadArchive {
+        thread_id: Uuid,
+    },
+    PinAdd {
+        room: Uuid,
+        message: Uuid,
+    },
+    PinRemove {
+        room: Uuid,
+        message: Uuid,
+    },
+    DraftSave {
+        room: Uuid,
+        content: String,
+    },
+    DraftClear {
+        room: Uuid,
+    },
+    Search {
+        q: String,
+        room: Option<Uuid>,
+        start_time: Option<DateTime<Utc>>,
+        end_time: Option<DateTime<Utc>>,
+        sender_id: Option<Uuid>,
+        content_type: Option<String>,
+        limit: Option<u64>,
+        offset: Option<u64>,
+    },
+    NotificationMarkRead {
+        id: Uuid,
+    },
+    NotificationMarkAllRead {
+        workspace_id: Option<Uuid>,
+    },
+    NotificationArchive {
+        id: Uuid,
+    },
+    PresenceUpdate {
+        status: UserPresenceStatus,
+    },
+    CustomStatusUpdate {
+        emoji: Option<String>,
+        text: Option<String>,
+        expires_at: Option<DateTime<Utc>>,
+    },
+    InviteCreate {
+        workspace: Uuid,
+        room: Option<Uuid>,
+        max_uses: Option<i32>,
+        expires_at: Option<DateTime<Utc>>,
+    },
+    InviteAccept {
+        code: String,
+    },
+    InviteRevoke {
+        id: Uuid,
+    },
+    BanCreate {
+        workspace: Uuid,
+        user: Uuid,
+        reason: Option<String>,
+        expires_at: Option<DateTime<Utc>>,
+    },
+    BanRemove {
+        workspace: Uuid,
+        user: Uuid,
+    },
+    VoiceJoin {
+        room: Uuid,
+    },
+    VoiceLeave {
+        room: Uuid,
+    },
+    VoiceMute {
+        room: Uuid,
+        muted: bool,
+    },
+    VoiceDeaf {
+        room: Uuid,
+        deafened: bool,
+    },
+    ScreenShare {
+        room: Uuid,
+        start: bool,
+    },
+    AiList {
+        room: Uuid,
+    },
+    AiUpsert {
+        room: Uuid,
+        model: Uuid,
+    },
+    AiDelete {
+        room: Uuid,
+        agent_id: Uuid,
+    },
+    AiStop {
+        room: Uuid,
+    },
+    UserSummary {
+        username: String,
+    },
+    ConversationPin {
+        room: Uuid,
+        pin: bool,
+    },
+    ConversationMute {
+        room: Uuid,
+        mute: bool,
+    },
+    ConversationNotifyLevel {
+        room: Uuid,
+        notify_level: String,
+    },
+    ConversationList,
+    DmCreate {
+        recipient: Uuid,
+    },
+    DmClose {
+        room: Uuid,
+    },
+    DmList,
+    MessageMarkRead {
+        room: Uuid,
+        message_ids: Vec<Uuid>,
+    },
+    MessageGetReaders {
+        message_id: Uuid,
+    },
+    MessageStar {
+        room: Uuid,
+        message: Uuid,
+        star: bool,
+    },
+    StarredList {
+        room: Option<Uuid>,
+        limit: Option<u64>,
+    },
+    MessageForward {
+        source_message_id: Uuid,
+        target_room: Uuid,
+    },
+}
+
+macro_rules! room_variants {
+    ($self:expr, $($variant:ident),* $(,)?) => {
+        match $self {
+            $( Self::$variant { room, .. } => Some(*room), )*
+            _ => None,
+        }
+    };
+}
+
+impl WsInMessage {
+    pub fn room_id(&self) -> Option<Uuid> {
+        room_variants!(
+            self,
+            Subscribe,
+            Unsubscribe,
+            TypingStart,
+            TypingStop,
+            ReadReceipt,
+            MessageCreate,
+            MessageList,
+            RoomUpdate,
+            RoomDelete,
+            RoomGet,
+            AccessGrant,
+            AccessRevoke,
+            StateSetReadSeq,
+            StateUpdateDnd,
+            MissedMessages,
+            ReactionAdd,
+            ReactionRemove,
+            ThreadCreate,
+            PinAdd,
+            PinRemove,
+            DraftSave,
+            DraftClear,
+            VoiceJoin,
+            VoiceLeave,
+            VoiceMute,
+            VoiceDeaf,
+            ScreenShare,
+            AiList,
+            AiUpsert,
+            AiDelete,
+            AiStop,
+            ConversationPin,
+            ConversationMute,
+            ConversationNotifyLevel,
+            DmClose,
+            MessageMarkRead,
+            MessageStar,
+        )
+        .or_else(|| match self {
+            Self::Search {
+                room: Some(room), ..
+            } => Some(*room),
+            Self::MessageForward { target_room, .. } => Some(*target_room),
+            _ => None,
+        })
+    }
+}
diff --git a/lib/channel/http/ws.rs b/lib/channel/http/ws.rs
new file mode 100644
index 0000000..f4d3373
--- /dev/null
+++ b/lib/channel/http/ws.rs
@@ -0,0 +1,153 @@
+use socketio::{EventPayload, Socket};
+use uuid::Uuid;
+
+use crate::{ChannelBus, ChannelError, ChannelResult};
+
+use super::handler::WsHandler;
+use super::out_event::{WsError, WsOutEvent};
+use super::types::WsInMessage;
+
+const CHANNEL_EVENT: &str = "channel.message";
+
+pub async fn register_message_handler(
+    bus: &ChannelBus,
+) -> crate::ChannelResult<()> {
+    let namespace = bus.inner.io.namespace(&bus.inner.config.namespace).await;
+
+    let bus_clone = bus.clone();
+    namespace
+        .on(CHANNEL_EVENT, move |socket, data: EventPayload| {
+            let bus = bus_clone.clone();
+            async move {
+                handle_inbound(&bus, &socket, data).await;
+            }
+        })
+        .await;
+
+    Ok(())
+}
+
+async fn handle_inbound(bus: &ChannelBus, socket: &Socket, data: EventPayload) {
+    let user_id = match socket.session_user() {
+        Some(id) => id,
+        None => {
+            tracing::warn!("channel message from unauthenticated socket");
+            send_error(socket, ChannelError::Unauthorized.to_ws_error()).await;
+            return;
+        }
+    };
+    let payload = match data.args.first() {
+        Some(v) => v,
+        None => {
+            tracing::warn!("channel message with empty args");
+            return;
+        }
+    };
+
+    let parsed = payload;
+
+    let text = serde_json::to_string(payload).unwrap_or_default();
+    if parsed
+        .get("type")
+        .and_then(|t| t.as_str())
+        == Some("ping")
+    {
+        let pong = WsOutEvent::Pong {
+            protocol_version: super::types::WS_PROTOCOL_VERSION,
+        };
+        send_event(socket, &pong).await.ok();
+        return;
+    }
+    if !check_rate_limit(bus, user_id).await {
+        send_error(socket, ChannelError::RateLimitExceeded.to_ws_error()).await;
+        return;
+    }
+    if text.len() > super::handler::MAX_TEXT_LEN {
+        send_error(
+            socket,
+            WsError {
+                code: 422,
+                error: "message_too_long".to_string(),
+                message: "message exceeds maximum length".to_string(),
+            },
+        )
+        .await;
+        return;
+    }
+    let request_id: Option<Uuid> = parsed
+        .get("_request_id")
+        .and_then(|r| serde_json::from_value(r.clone()).ok());
+    match serde_json::from_value::<WsInMessage>(payload.clone()) {
+        Ok(in_msg) => match WsHandler::handle(bus, user_id, in_msg).await {
+            Ok(Some(event)) => {
+                let rid = request_id.unwrap_or(Uuid::nil());
+                let resp = WsOutEvent::Response {
+                    request_id: rid,
+                    data: serde_json::to_value(&event).unwrap_or_default(),
+                };
+                send_event(socket, &resp).await.ok();
+            }
+            Ok(None) => {
+                let rid = request_id.unwrap_or(Uuid::nil());
+                let ack = WsOutEvent::Response {
+                    request_id: rid,
+                    data: serde_json::json!({"ok": true}),
+                };
+                send_event(socket, &ack).await.ok();
+            }
+            Err(e) => {
+                tracing::warn!(user_id = %user_id, error = %e, "WS message processing failed");
+                let rid = request_id.unwrap_or(Uuid::nil());
+                let err_resp = WsOutEvent::Response {
+                    request_id: rid,
+                    data: serde_json::to_value(&e.to_ws_error())
+                        .unwrap_or_default(),
+                };
+                send_event(socket, &err_resp).await.ok();
+            }
+        },
+        Err(e) => {
+            tracing::warn!(error = %e, "WS transport parse error");
+            send_error(
+                socket,
+                WsError {
+                    code: 400,
+                    error: "parse_error".to_string(),
+                    message: e.to_string(),
+                },
+            )
+            .await;
+        }
+    }
+}
+
+async fn check_rate_limit(bus: &ChannelBus, user_id: Uuid) -> bool {
+    bus.inner
+        .rate_limiter
+        .check_rate_limit(user_id, "ws_message")
+        .await
+        .unwrap_or(true)
+}
+
+async fn send_event(socket: &Socket, event: &WsOutEvent) -> ChannelResult<()> {
+    let json = serde_json::to_string(event)?;
+    socket
+        .emit(CHANNEL_EVENT, &json)
+        .await
+        .map_err(|e| {
+            tracing::warn!(error = %e, "WS send failed");
+            ChannelError::SocketIo(e)
+        })
+}
+
+async fn send_error(socket: &Socket, error: WsError) {
+    let json = serde_json::json!({
+        "type": "error",
+        "code": error.code,
+        "error": error.error,
+        "message": error.message,
+    });
+    if let Err(e) = socket.emit(CHANNEL_EVENT, json.to_string()).await {
+        tracing::warn!(error = %e, "WS error send failed");
+    }
+}
diff --git a/lib/channel/lib.rs b/lib/channel/lib.rs
new file mode 100644
index 0000000..d0e7c26
--- /dev/null
+++ b/lib/channel/lib.rs
@@ -0,0 +1,39 @@
+mod ack;
+mod bus;
+mod cdn;
+mod circuit_breaker;
+mod config;
+mod dedup;
+mod envelope;
+mod error;
+pub mod event;
+pub mod http;
+mod metrics;
+mod pagination;
+mod reconnect;
+pub mod rooms;
+mod search;
+mod security;
+mod seq;
+mod token;
+
+pub use ack::{AckRequest, AckResponse, AckStatus, AckTracker, MessageAck};
+pub use bus::ChannelBus;
+pub use cdn::{CdnManager, CdnStoredFile};
+pub use circuit_breaker::{CircuitBreaker, CircuitBreakerError};
+pub use config::ChannelBusConfig;
+pub use dedup::DeduplicationManager;
+pub use envelope::ChannelEnvelope;
+pub use error::{ChannelError, ChannelResult};
+pub use metrics::ChannelMetrics;
+pub use pagination::{
+    MessageItem, MessagePage, MessagePagination, PaginationDirection,
+    PaginationParams,
+};
+pub use reconnect::{ClientState, MissedMessage, ReconnectManager};
+pub use search::{SearchEngine, SearchHit, SearchQuery, SearchResult};
+pub use security::{CsrfProtection, RateLimiter};
+pub use seq::SeqAllocator;
+pub use token::{
+    ChannelAccessToken, ChannelTokenApply, ChannelTokenContext, TOKEN_TTL_SECS,
+};
diff --git a/lib/channel/metrics.rs b/lib/channel/metrics.rs
new file mode 100644
index 0000000..7f32113
--- /dev/null
+++ b/lib/channel/metrics.rs
@@ -0,0 +1,45 @@
+use std::sync::Arc;
+
+#[derive(Clone)]
+pub struct ChannelMetrics {
+    pub messages_sent: Arc<std::sync::atomic::AtomicU64>,
+    pub messages_received: Arc<std::sync::atomic::AtomicU64>,
+    pub messages_failed: Arc<std::sync::atomic::AtomicU64>,
+    pub active_connections: Arc<std::sync::atomic::AtomicI64>,
+}
+
+impl ChannelMetrics {
+    pub fn new() -> Self {
+        Self {
+            messages_sent: Arc::new(std::sync::atomic::AtomicU64::new(0)),
+            messages_received: Arc::new(std::sync::atomic::AtomicU64::new(0)),
+            messages_failed: Arc::new(std::sync::atomic::AtomicU64::new(0)),
+            active_connections: Arc::new(std::sync::atomic::AtomicI64::new(0)),
+        }
+    }
+
+    pub fn increment_sent(&self) {
+        self.messages_sent
+            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    pub fn increment_received(&self) {
+        self.messages_received
+            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    pub fn increment_failed(&self) {
+        self.messages_failed
+            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    pub fn increment_connections(&self) {
+        self.active_connections
+            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    pub fn decrement_connections(&self) {
+        self.active_connections
+            .fetch_sub(1, std::sync::atomic::Ordering::Relaxed);
+    }
+}
diff --git a/lib/channel/pagination.rs b/lib/channel/pagination.rs
new file mode 100644
index 0000000..811bf1c
--- /dev/null
+++ b/lib/channel/pagination.rs
@@ -0,0 +1,220 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::rooms::RM_COLUMNS;
+use crate::{ChannelError, ChannelResult};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessagePage {
+    pub messages: Vec<MessageItem>,
+    pub has_more: bool,
+    pub next_cursor: Option<String>,
+    pub prev_cursor: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MessageItem {
+    pub id: Uuid,
+    pub room_id: Uuid,
+    pub seq: i64,
+    pub thread: Option<Uuid>,
+    pub parent: Option<Uuid>,
+    pub content: String,
+    pub content_type: String,
+    pub pinned: bool,
+    pub system_type: Option<String>,
+    pub metadata: serde_json::Value,
+    pub sender_id: Uuid,
+    pub send_at: chrono::DateTime<chrono::Utc>,
+    pub edited_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PaginationParams {
+    pub room_id: Uuid,
+    pub limit: u64,
+    pub cursor: Option<String>,
+    pub direction: PaginationDirection,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum PaginationDirection {
+    Before,
+    After,
+}
+
+pub struct MessagePagination {
+    db: db::AppDatabase,
+}
+
+impl MessagePagination {
+    pub fn new(db: db::AppDatabase) -> Self {
+        Self { db }
+    }
+
+    pub async fn get_messages(
+        &self,
+        params: PaginationParams,
+    ) -> ChannelResult<MessagePage> {
+        let limit = std::cmp::Ord::min(params.limit, 100) as i64;
+        let cursor_seq = params.cursor.and_then(|c| c.parse::<i64>().ok());
+
+        let messages = match (params.direction, cursor_seq) {
+            (PaginationDirection::Before, Some(seq)) => {
+                db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+                    db::sqlx::AssertSqlSafe(format!(
+                        "SELECT {RM_COLUMNS} FROM room_message \
+                     WHERE room = $1 AND seq < $2 AND deleted_at IS NULL \
+                     ORDER BY seq DESC LIMIT $3"
+                    )),
+                )
+                .bind(params.room_id)
+                .bind(seq)
+                .bind(limit + 1)
+                .fetch_all(self.db.reader())
+                .await?
+            }
+            (PaginationDirection::After, Some(seq)) => {
+                db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+                    db::sqlx::AssertSqlSafe(format!(
+                        "SELECT {RM_COLUMNS} FROM room_message \
+                     WHERE room = $1 AND seq > $2 AND deleted_at IS NULL \
+                     ORDER BY seq ASC LIMIT $3"
+                    )),
+                )
+                .bind(params.room_id)
+                .bind(seq)
+                .bind(limit + 1)
+                .fetch_all(self.db.reader())
+                .await?
+            }
+            _ => {
+                db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+                    db::sqlx::AssertSqlSafe(format!(
+                        "SELECT {RM_COLUMNS} FROM room_message \
+                     WHERE room = $1 AND deleted_at IS NULL \
+                     ORDER BY seq DESC LIMIT $2"
+                    )),
+                )
+                .bind(params.room_id)
+                .bind(limit + 1)
+                .fetch_all(self.db.reader())
+                .await?
+            }
+        };
+
+        let has_more = messages.len() > limit as usize;
+        let messages: Vec<_> =
+            messages.into_iter().take(limit as usize).collect();
+
+        let next_cursor = if has_more {
+            messages.last().map(|m| m.seq.to_string())
+        } else {
+            None
+        };
+        let prev_cursor = messages.first().map(|m| m.seq.to_string());
+
+        let items: Vec<MessageItem> = messages
+            .into_iter()
+            .map(|m| MessageItem {
+                id: m.id,
+                room_id: m.room,
+                seq: m.seq,
+                thread: m.thread,
+                parent: m.parent,
+                content: m.content,
+                content_type: m.content_type,
+                pinned: m.pinned,
+                system_type: m.system_type,
+                metadata: m.metadata,
+                sender_id: m.author,
+                send_at: m.created_at,
+                edited_at: m.edited_at,
+            })
+            .collect();
+
+        Ok(MessagePage {
+            messages: items,
+            has_more,
+            next_cursor,
+            prev_cursor,
+        })
+    }
+
+    pub async fn get_messages_around(
+        &self,
+        room_id: Uuid,
+        message_id: Uuid,
+        context_size: i64,
+    ) -> ChannelResult<MessagePage> {
+        let target = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            db::sqlx::AssertSqlSafe(format!(
+                "SELECT {RM_COLUMNS} FROM room_message \
+                 WHERE id = $1 AND room = $2 AND deleted_at IS NULL"
+            )),
+        )
+        .bind(message_id)
+        .bind(room_id)
+        .fetch_optional(self.db.reader())
+        .await?
+        .ok_or(ChannelError::Internal("message not found".to_string()))?;
+
+        let before = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            db::sqlx::AssertSqlSafe(format!(
+                "SELECT {RM_COLUMNS} FROM room_message \
+                 WHERE room = $1 AND seq < $2 AND deleted_at IS NULL \
+                 ORDER BY seq DESC LIMIT $3"
+            )),
+        )
+        .bind(room_id)
+        .bind(target.seq)
+        .bind(context_size)
+        .fetch_all(self.db.reader())
+        .await?;
+
+        let after = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            db::sqlx::AssertSqlSafe(format!(
+                "SELECT {RM_COLUMNS} FROM room_message \
+                 WHERE room = $1 AND seq > $2 AND deleted_at IS NULL \
+                 ORDER BY seq ASC LIMIT $3"
+            )),
+        )
+        .bind(room_id)
+        .bind(target.seq)
+        .bind(context_size)
+        .fetch_all(self.db.reader())
+        .await?;
+
+        let mut all_messages = before;
+        all_messages.reverse();
+        all_messages.push(target);
+        all_messages.extend(after);
+
+        let items: Vec<MessageItem> = all_messages
+            .into_iter()
+            .map(|m| MessageItem {
+                id: m.id,
+                room_id: m.room,
+                seq: m.seq,
+                thread: m.thread,
+                parent: m.parent,
+                content: m.content,
+                content_type: m.content_type,
+                pinned: m.pinned,
+                system_type: m.system_type,
+                metadata: m.metadata,
+                sender_id: m.author,
+                send_at: m.created_at,
+                edited_at: m.edited_at,
+            })
+            .collect();
+
+        Ok(MessagePage {
+            messages: items,
+            has_more: false,
+            next_cursor: None,
+            prev_cursor: None,
+        })
+    }
+}
diff --git a/lib/channel/reconnect.rs b/lib/channel/reconnect.rs
new file mode 100644
index 0000000..97d394c
--- /dev/null
+++ b/lib/channel/reconnect.rs
@@ -0,0 +1,113 @@
+use std::collections::HashMap;
+use uuid::Uuid;
+
+use model::room::RoomMessageModel;
+use serde::{Deserialize, Serialize};
+
+use crate::rooms::RM_COLUMNS;
+use crate::ChannelResult;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ClientState {
+    pub user_id: Uuid,
+    pub last_seq: HashMap<Uuid, i64>,
+    pub last_seen: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MissedMessage {
+    pub room_id: Uuid,
+    pub message_id: Uuid,
+    pub seq: i64,
+    pub content: String,
+    pub sender_id: Uuid,
+    pub send_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Clone)]
+pub struct ReconnectManager {
+    cache: cache::AppCache,
+    db: db::AppDatabase,
+}
+
+impl ReconnectManager {
+    pub fn new(cache: cache::AppCache, db: db::AppDatabase) -> Self {
+        Self { cache, db }
+    }
+
+    pub async fn save_client_state(
+        &self,
+        user_id: Uuid,
+        room_id: Uuid,
+        last_seq: i64,
+    ) -> ChannelResult<()> {
+        let key = format!("client:state:{}:{}", user_id, room_id);
+        self.cache.set(&key, &last_seq.to_string()).await?;
+        if let Some(cluster) = &self.cache.cluster {
+            cluster
+                .expire(&key, std::time::Duration::from_secs(86400))
+                .await?;
+        }
+        Ok(())
+    }
+
+    pub async fn get_last_seq(
+        &self,
+        user_id: Uuid,
+        room_id: Uuid,
+    ) -> ChannelResult<Option<i64>> {
+        let key = format!("client:state:{}:{}", user_id, room_id);
+        let value: Option<String> = self.cache.get(&key).await?;
+        Ok(value.and_then(|v| v.parse::<i64>().ok()))
+    }
+
+    pub async fn get_missed_messages(
+        &self,
+        room_id: Uuid,
+        since_seq: i64,
+    ) -> ChannelResult<Vec<MissedMessage>> {
+        let messages = db::sqlx::query_as::<_, RoomMessageModel>(
+            db::sqlx::AssertSqlSafe(format!(
+                "SELECT {RM_COLUMNS} FROM room_message \
+                 WHERE room = $1 AND seq > $2 AND deleted_at IS NULL \
+                 ORDER BY seq ASC \
+                 LIMIT 100"
+            )),
+        )
+        .bind(room_id)
+        .bind(since_seq)
+        .fetch_all(self.db.reader())
+        .await?;
+
+        let missed: Vec<MissedMessage> = messages
+            .into_iter()
+            .map(|m| MissedMessage {
+                room_id: m.room,
+                message_id: m.id,
+                seq: m.seq,
+                content: m.content,
+                sender_id: m.author,
+                send_at: m.created_at,
+            })
+            .collect();
+
+        Ok(missed)
+    }
+
+    pub async fn handle_reconnect(
+        &self,
+        _user_id: Uuid,
+        room_states: HashMap<Uuid, i64>,
+    ) -> ChannelResult<HashMap<Uuid, Vec<MissedMessage>>> {
+        let mut result = HashMap::new();
+
+        for (room_id, client_seq) in room_states {
+            let missed = self.get_missed_messages(room_id, client_seq).await?;
+            if !missed.is_empty() {
+                result.insert(room_id, missed);
+            }
+        }
+
+        Ok(result)
+    }
+}
diff --git a/lib/channel/richtext.rs b/lib/channel/richtext.rs
new file mode 100644
index 0000000..3dc4743
--- /dev/null
+++ b/lib/channel/richtext.rs
@@ -0,0 +1,112 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RichTextBlock {
+    pub block_type: BlockType,
+    pub content: String,
+    pub attributes: Option<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum BlockType {
+    Text,
+    Code,
+    Quote,
+    Link,
+    Mention,
+    Emoji,
+    Image,
+}
+
+pub struct RichTextRenderer;
+
+impl RichTextRenderer {
+    pub fn new() -> Self {
+        Self {}
+    }
+
+    pub fn parse_markdown(&self, content: &str) -> Vec<RichTextBlock> {
+        vec![RichTextBlock {
+            block_type: BlockType::Text,
+            content: content.to_string(),
+            attributes: None,
+        }]
+    }
+
+    pub fn parse_mentions(&self, content: &str) -> Vec<Uuid> {
+        content
+            .split_whitespace()
+            .filter(|w| w.starts_with('@'))
+            .filter_map(|w| Uuid::parse_str(&w[1..]).ok())
+            .collect()
+    }
+
+    pub fn highlight_code(&self, code: &str, language: &str) -> String {
+        format!("```{}\n{}\n```", language, code)
+    }
+
+    pub fn render_to_html(&self, blocks: &[RichTextBlock]) -> String {
+        blocks
+            .iter()
+            .map(|block| match block.block_type {
+                BlockType::Text => {
+                    format!("<p>{}</p>", html_escape(&block.content))
+                }
+                BlockType::Code => format!(
+                    "<pre><code>{}</code></pre>",
+                    html_escape(&block.content)
+                ),
+                BlockType::Quote => format!(
+                    "<blockquote>{}</blockquote>",
+                    html_escape(&block.content)
+                ),
+                BlockType::Link => {
+                    let safe_href = sanitize_uri(&block.content);
+                    format!(
+                        "<a href=\"{}\">{}</a>",
+                        html_escape(&safe_href),
+                        html_escape(&block.content)
+                    )
+                }
+                BlockType::Mention => format!(
+                    "<span class=\"mention\">@{}</span>",
+                    html_escape(&block.content)
+                ),
+                BlockType::Emoji => format!(
+                    "<span class=\"emoji\">{}</span>",
+                    html_escape(&block.content)
+                ),
+                BlockType::Image => {
+                    let safe_src = sanitize_uri(&block.content);
+                    if safe_src.is_empty() {
+                        String::new()
+                    } else {
+                        format!("<img src=\"{}\" />", html_escape(&safe_src))
+                    }
+                }
+            })
+            .collect::<Vec<_>>()
+            .join("\n")
+    }
+}
+fn sanitize_uri(uri: &str) -> String {
+    let lower = uri.to_lowercase();
+    if lower.starts_with("http://")
+        || lower.starts_with("https://")
+        || lower.starts_with("mailto:")
+    {
+        uri.to_string()
+    } else {
+        String::new()
+    }
+}
+
+fn html_escape(s: &str) -> String {
+    s.replace('&', "&amp;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+        .replace('"', "&quot;")
+        .replace('\'', "&#x27;")
+}
diff --git a/lib/channel/rooms.rs b/lib/channel/rooms.rs
new file mode 100644
index 0000000..b079ac8
--- /dev/null
+++ b/lib/channel/rooms.rs
@@ -0,0 +1,221 @@
+use cache::AppCache;
+use db::{AppDatabase, sqlx};
+use model::room::RoomMessageModel;
+use serde::Serialize;
+use uuid::Uuid;
+
+use crate::{ChannelBusConfig, ChannelResult};
+
+pub(crate) const RM_COLUMNS: &str =
+    "id, room, seq, thread, parent, author, content, content_type, pinned, \
+     system_type, metadata, edited_at, created_at, updated_at, deleted_at";
+
+pub(crate) fn room_socket_name(room: Uuid) -> String {
+    format!("room:{room}")
+}
+
+pub(crate) fn user_rooms_cache_key(user: Uuid) -> String {
+    format!("channel:user:{user}:rooms")
+}
+#[derive(Debug, Serialize)]
+pub struct RoomListItem {
+    pub id: Uuid,
+    pub name: String,
+    pub topic: Option<String>,
+    pub room_type: String,
+    pub is_private: bool,
+    pub category: Option<Uuid>,
+    pub workspace_id: Uuid,
+}
+#[derive(Debug, Serialize)]
+pub struct CategoryListItem {
+    pub id: Uuid,
+    pub name: String,
+    pub position: i32,
+}
+pub async fn user_rooms_for_api(
+    db: &AppDatabase,
+    cache: &AppCache,
+    config: &ChannelBusConfig,
+    user: Uuid,
+) -> ChannelResult<Vec<RoomListItem>> {
+    let room_ids = user_rooms(db, cache, config, user).await?;
+    if room_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let rows = sqlx::query_as::<_, (Uuid, String, Option<String>, String, bool, Option<Uuid>, Uuid)>(
+        "SELECT id, name, topic, room_type, is_private, parent, wk \
+         FROM room \
+         WHERE id = ANY($1) AND deleted_at IS NULL AND is_archived = false \
+         ORDER BY name",
+    )
+    .bind(&room_ids)
+    .fetch_all(db.reader())
+    .await?;
+
+    Ok(rows
+        .into_iter()
+        .map(|(id, name, topic, room_type, is_private, category, workspace_id)| RoomListItem {
+            id,
+            name,
+            topic,
+            room_type,
+            is_private,
+            category,
+            workspace_id,
+        })
+        .collect())
+}
+pub async fn user_categories_for_api(
+    db: &AppDatabase,
+    cache: &AppCache,
+    config: &ChannelBusConfig,
+    user: Uuid,
+) -> ChannelResult<Vec<CategoryListItem>> {
+    let room_ids = user_rooms(db, cache, config, user).await?;
+    if room_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+    let wk_rows = sqlx::query_as::<_, (Uuid,)>(
+        "SELECT DISTINCT wk FROM room WHERE id = ANY($1) AND deleted_at IS NULL",
+    )
+    .bind(&room_ids)
+    .fetch_all(db.reader())
+    .await?;
+
+    let wk_ids: Vec<Uuid> = wk_rows.into_iter().map(|r| r.0).collect();
+    if wk_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let rows = sqlx::query_as::<_, (Uuid, String, i32)>(
+        "SELECT id, name, position FROM room_category WHERE wk = ANY($1) ORDER BY position, name",
+    )
+    .bind(&wk_ids)
+    .fetch_all(db.reader())
+    .await?;
+
+    Ok(rows
+        .into_iter()
+        .map(|(id, name, position)| CategoryListItem { id, name, position })
+        .collect())
+}
+
+pub(crate) async fn user_rooms(
+    db: &AppDatabase,
+    cache: &AppCache,
+    config: &ChannelBusConfig,
+    user: Uuid,
+) -> ChannelResult<Vec<Uuid>> {
+    let key = user_rooms_cache_key(user);
+    if let Some(rooms) = cache.get::<Vec<Uuid>>(&key).await? {
+        return Ok(rooms);
+    }
+
+    let rooms = load_user_rooms(db, user).await?;
+    cache_set_with_ttl(cache, &key, &rooms, config.room_cache_ttl_hint).await?;
+    Ok(rooms)
+}
+
+pub(crate) async fn refresh_user_rooms_cache(
+    db: &AppDatabase,
+    cache: &AppCache,
+    config: &ChannelBusConfig,
+    user: Uuid,
+) -> ChannelResult<Vec<Uuid>> {
+    let key = user_rooms_cache_key(user);
+    cache.remove(&key).await?;
+    let rooms = load_user_rooms(db, user).await?;
+    cache_set_with_ttl(cache, &key, &rooms, config.room_cache_ttl_hint).await?;
+    Ok(rooms)
+}
+
+async fn cache_set_with_ttl<T>(
+    cache: &AppCache,
+    key: &str,
+    value: &T,
+    ttl: Option<std::time::Duration>,
+) -> ChannelResult<()>
+where
+    T: serde::Serialize + serde::de::DeserializeOwned,
+{
+    cache.set(key, value).await?;
+    if let Some(ttl) = ttl {
+        if let Some(cluster) = &cache.cluster {
+            cluster.expire(key, ttl).await?;
+        }
+    }
+    Ok(())
+}
+
+pub(crate) async fn active_workspace_users(
+    db: &AppDatabase,
+    wk: Uuid,
+) -> ChannelResult<Vec<Uuid>> {
+    let rows = sqlx::query_as::<_, (Uuid,)>(
+        "SELECT \"user\" FROM wk_member WHERE wk = $1 AND leave_at IS NULL",
+    )
+    .bind(wk)
+    .fetch_all(db.reader())
+    .await?;
+    Ok(rows.into_iter().map(|row| row.0).collect())
+}
+
+pub(crate) async fn room_workspace(
+    db: &AppDatabase,
+    room: Uuid,
+) -> ChannelResult<Option<Uuid>> {
+    let row = sqlx::query_as::<_, (Uuid,)>("SELECT wk FROM room WHERE id = $1")
+        .bind(room)
+        .fetch_optional(db.reader())
+        .await?;
+    Ok(row.map(|row| row.0))
+}
+
+pub(crate) async fn catchup_messages(
+    db: &AppDatabase,
+    config: &ChannelBusConfig,
+    room: Uuid,
+    after_seq: i64,
+) -> ChannelResult<Vec<RoomMessageModel>> {
+    let rows = sqlx::query_as::<_, RoomMessageModel>(
+        db::sqlx::AssertSqlSafe(format!(
+            "SELECT {RM_COLUMNS} FROM room_message \
+             WHERE room = $1 AND seq > $2 AND deleted_at IS NULL \
+             ORDER BY seq ASC \
+             LIMIT $3"
+        )),
+    )
+    .bind(room)
+    .bind(after_seq)
+    .bind(config.catchup_limit)
+    .fetch_all(db.reader())
+    .await?;
+    Ok(rows)
+}
+
+async fn load_user_rooms(
+    db: &AppDatabase,
+    user: Uuid,
+) -> ChannelResult<Vec<Uuid>> {
+    let rows = sqlx::query_as::<_, (Uuid,)>(
+        "SELECT r.id \
+         FROM room r \
+         INNER JOIN wk_member wm ON wm.wk = r.wk \
+         WHERE wm.\"user\" = $1 \
+           AND wm.leave_at IS NULL \
+           AND r.deleted_at IS NULL \
+           AND r.is_archived = false \
+           AND (r.is_private = false \
+                OR EXISTS ( \
+                    SELECT 1 FROM room_permission_overwrite po \
+                    WHERE po.room = r.id AND po.target_id = $1 \
+                )) \
+         ORDER BY r.id",
+    )
+    .bind(user)
+    .fetch_all(db.reader())
+    .await?;
+    Ok(rows.into_iter().map(|row| row.0).collect())
+}
diff --git a/lib/channel/search.rs b/lib/channel/search.rs
new file mode 100644
index 0000000..8b52932
--- /dev/null
+++ b/lib/channel/search.rs
@@ -0,0 +1,137 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::ChannelResult;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SearchQuery {
+    pub query: String,
+    pub room_id: Option<Uuid>,
+    pub user_id: Option<Uuid>,
+    pub limit: u64,
+    pub offset: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SearchResult {
+    pub total: u64,
+    pub hits: Vec<SearchHit>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SearchHit {
+    pub message_id: Uuid,
+    pub room_id: Uuid,
+    pub content: String,
+    pub highlighted: String,
+    pub sender_id: Uuid,
+    pub send_at: chrono::DateTime<chrono::Utc>,
+    pub score: f64,
+}
+
+pub struct SearchEngine {
+    db: db::AppDatabase,
+}
+
+impl SearchEngine {
+    pub fn new(db: db::AppDatabase) -> Self {
+        Self { db }
+    }
+
+    pub async fn search(
+        &self,
+        query: SearchQuery,
+    ) -> ChannelResult<SearchResult> {
+        let search_term = format!("%{}%", escape_like(&query.query));
+        let room_filter = query.room_id;
+        let user_filter = query.user_id;
+
+        let count: (i64,) = db::sqlx::query_as(
+            "SELECT COUNT(*) FROM room_message \
+             WHERE ($1::uuid IS NULL OR room = $1) \
+             AND ($2::uuid IS NULL OR author = $2) \
+             AND content LIKE $3 ESCAPE '\\' \
+             AND deleted_at IS NULL",
+        )
+        .bind(room_filter)
+        .bind(user_filter)
+        .bind(&search_term)
+        .fetch_one(self.db.reader())
+        .await?;
+
+        let total = count.0 as u64;
+
+        let messages = db::sqlx::query_as::<_, model::room::RoomMessageModel>(
+            "SELECT id, room, seq, thread, parent, author, content, content_type, pinned, \
+             system_type, metadata, edited_at, created_at, updated_at, deleted_at \
+             FROM room_message \
+             WHERE ($1::uuid IS NULL OR room = $1) \
+             AND ($2::uuid IS NULL OR author = $2) \
+             AND content LIKE $3 ESCAPE '\\' \
+             AND deleted_at IS NULL \
+             ORDER BY created_at DESC LIMIT $4 OFFSET $5"
+        )
+        .bind(room_filter)
+        .bind(user_filter)
+        .bind(&search_term)
+        .bind(query.limit as i64)
+        .bind(query.offset as i64)
+        .fetch_all(self.db.reader())
+        .await?;
+
+        let hits: Vec<SearchHit> = messages
+            .into_iter()
+            .map(|m| SearchHit {
+                message_id: m.id,
+                room_id: m.room,
+                content: m.content.clone(),
+                highlighted: highlight_text(&m.content, &query.query),
+                sender_id: m.author,
+                send_at: m.created_at,
+                score: 1.0,
+            })
+            .collect();
+
+        Ok(SearchResult { total, hits })
+    }
+}
+fn escape_like(input: &str) -> String {
+    let mut out = String::with_capacity(input.len());
+    for ch in input.chars() {
+        match ch {
+            '\\' => out.push_str("\\\\"),
+            '%' => out.push_str("\\%"),
+            '_' => out.push_str("\\_"),
+            _ => out.push(ch),
+        }
+    }
+    out
+}
+fn highlight_text(content: &str, query: &str) -> String {
+    let lower_content = content.to_lowercase();
+    let lower_query = query.to_lowercase();
+    let char_pos = match lower_content.find(&lower_query) {
+        Some(p) => p,
+        None => return content.to_string(),
+    };
+    let match_chars = lower_content[..char_pos].chars().count();
+    let query_chars = lower_query.chars().count();
+
+    let mut before = String::new();
+    let mut matched = String::new();
+    let mut after = String::new();
+    let mut char_idx = 0;
+
+    for ch in content.chars() {
+        if char_idx < match_chars {
+            before.push(ch);
+        } else if char_idx < match_chars + query_chars {
+            matched.push(ch);
+        } else {
+            after.push(ch);
+        }
+        char_idx += 1;
+    }
+
+    format!("{}<mark>{}</mark>{}", before, matched, after)
+}
diff --git a/lib/channel/security.rs b/lib/channel/security.rs
new file mode 100644
index 0000000..7c2e297
--- /dev/null
+++ b/lib/channel/security.rs
@@ -0,0 +1,152 @@
+use std::time::Duration;
+use uuid::Uuid;
+
+use crate::{ChannelError, ChannelResult};
+
+const RATE_LIMIT_SCRIPT: &str = r#"
+local key = KEYS[1]
+local max = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+local current = tonumber(redis.call('INCR', key))
+if current == 1 then
+    redis.call('EXPIRE', key, window)
+end
+if current > max then
+    return 0
+end
+return 1
+"#;
+
+#[derive(Clone)]
+pub struct RateLimiter {
+    cache: cache::AppCache,
+    max_requests: u32,
+    window: Duration,
+}
+
+impl RateLimiter {
+    pub fn new(cache: cache::AppCache) -> Self {
+        Self {
+            cache,
+            max_requests: 100,
+            window: Duration::from_secs(60),
+        }
+    }
+
+    pub fn with_config(
+        cache: cache::AppCache,
+        max_requests: u32,
+        window: Duration,
+    ) -> Self {
+        Self {
+            cache,
+            max_requests,
+            window,
+        }
+    }
+
+    pub async fn check_rate_limit(
+        &self,
+        user_id: Uuid,
+        action: &str,
+    ) -> ChannelResult<bool> {
+        let cluster = require_cluster(&self.cache)?;
+        let key = format!("ratelimit:{}:{}", user_id, action);
+        let mut conn = cluster.conn();
+
+        let allowed: i64 = redis::Cmd::new()
+            .arg("EVAL")
+            .arg(RATE_LIMIT_SCRIPT)
+            .arg(1)
+            .arg(&key)
+            .arg(self.max_requests)
+            .arg(self.window.as_secs())
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        Ok(allowed == 1)
+    }
+
+    pub async fn get_remaining(
+        &self,
+        user_id: Uuid,
+        action: &str,
+    ) -> ChannelResult<u32> {
+        let key = format!("ratelimit:{}:{}", user_id, action);
+        let count: Option<u32> = self.cache.get(&key).await?;
+        let current = count.unwrap_or(0);
+        Ok(self.max_requests.saturating_sub(current))
+    }
+}
+
+const CSRF_TTL_SECS: u64 = 3600;
+
+#[derive(Clone)]
+pub struct CsrfProtection {
+    cache: cache::AppCache,
+}
+
+impl CsrfProtection {
+    pub fn new(cache: cache::AppCache) -> Self {
+        Self { cache }
+    }
+
+    pub async fn generate_token(&self, user_id: Uuid) -> ChannelResult<String> {
+        let token = Uuid::new_v4().to_string();
+        let key = format!("csrf:{}:{}", user_id, token);
+        let cluster = require_cluster(&self.cache)?;
+        let mut conn = cluster.conn();
+
+        let _: () = redis::Cmd::new()
+            .arg("SET")
+            .arg(&key)
+            .arg("1")
+            .arg("EX")
+            .arg(CSRF_TTL_SECS)
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        Ok(token)
+    }
+
+    pub async fn validate_token(
+        &self,
+        user_id: Uuid,
+        token: &str,
+    ) -> ChannelResult<bool> {
+        let key = format!("csrf:{}:{}", user_id, token);
+        let cluster = require_cluster(&self.cache)?;
+        let mut conn = cluster.conn();
+        const VALIDATE_SCRIPT: &str = r#"
+local key = KEYS[1]
+local exists = redis.call('EXISTS', key)
+if exists == 1 then
+    redis.call('DEL', key)
+    return 1
+end
+return 0
+"#;
+
+        let valid: i64 = redis::Cmd::new()
+            .arg("EVAL")
+            .arg(VALIDATE_SCRIPT)
+            .arg(1)
+            .arg(&key)
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        Ok(valid == 1)
+    }
+}
+
+pub(crate) fn require_cluster(
+    cache: &cache::AppCache,
+) -> ChannelResult<&cache::ClusterCache> {
+    cache
+        .cluster
+        .as_ref()
+        .ok_or(ChannelError::Internal("no cluster cache".to_string()))
+}
diff --git a/lib/channel/seq.rs b/lib/channel/seq.rs
new file mode 100644
index 0000000..129b417
--- /dev/null
+++ b/lib/channel/seq.rs
@@ -0,0 +1,185 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicI64, Ordering};
+
+use dashmap::DashMap;
+use tokio::sync::Mutex;
+use uuid::Uuid;
+
+use crate::{ChannelError, ChannelResult, security::require_cluster};
+
+const SEQ_KEY_PREFIX: &str = "room:seq:";
+const DEFAULT_SEGMENT_SIZE: u64 = 1024;
+const MAX_REFRESH_RETRIES: u32 = 3;
+
+const BOOTSTRAP_SCRIPT: &str = r#"
+local key = KEYS[1]
+local db_max = tonumber(ARGV[1])
+local current = tonumber(redis.call('GET', key) or '0')
+if current < db_max then
+    redis.call('SET', key, db_max)
+end
+return tonumber(redis.call('GET', key))
+"#;
+
+struct SegmentState {
+    end: i64,
+    next: AtomicI64,
+}
+
+pub struct SeqAllocator(Arc<SeqAllocatorInner>);
+
+struct SeqAllocatorInner {
+    cache: cache::AppCache,
+    db: db::AppDatabase,
+    segments: DashMap<Uuid, Arc<SegmentState>>,
+    refresh_locks: DashMap<Uuid, Arc<Mutex<()>>>,
+    segment_size: u64,
+}
+
+impl Clone for SeqAllocator {
+    fn clone(&self) -> Self {
+        Self(Arc::clone(&self.0))
+    }
+}
+
+impl SeqAllocator {
+    pub fn new(cache: cache::AppCache, db: db::AppDatabase) -> Self {
+        Self::with_segment_size(cache, db, DEFAULT_SEGMENT_SIZE)
+    }
+
+    pub fn with_segment_size(
+        cache: cache::AppCache,
+        db: db::AppDatabase,
+        size: u64,
+    ) -> Self {
+        Self(Arc::new(SeqAllocatorInner {
+            cache,
+            db,
+            segments: DashMap::new(),
+            refresh_locks: DashMap::new(),
+            segment_size: if size > 0 { size } else { DEFAULT_SEGMENT_SIZE },
+        }))
+    }
+
+    pub async fn seq(&self, room: Uuid) -> ChannelResult<i64> {
+        for _ in 0..MAX_REFRESH_RETRIES {
+            if let Some(seq) = self.try_allocate(&room) {
+                return Ok(seq);
+            }
+
+            let lock = self.get_refresh_lock(room);
+            let _guard = lock.lock().await;
+
+            if let Some(seq) = self.try_allocate(&room) {
+                return Ok(seq);
+            }
+
+            self.refresh_segment(room).await?;
+            self.0.refresh_locks.remove(&room);
+        }
+
+        Err(ChannelError::Internal(
+            "seq allocation exhausted".to_string(),
+        ))
+    }
+
+    pub async fn bootstrap(&self, room: Uuid) -> ChannelResult<i64> {
+        let db_max = self.db_max_seq(room).await?;
+        if db_max == 0 {
+            return Ok(0);
+        }
+
+        let key = format!("{}{}", SEQ_KEY_PREFIX, room);
+        let cluster = require_cluster(&self.0.cache)?;
+        let mut conn = cluster.conn();
+
+        let current: i64 = redis::Cmd::new()
+            .arg("EVAL")
+            .arg(BOOTSTRAP_SCRIPT)
+            .arg(1)
+            .arg(&key)
+            .arg(db_max)
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        self.0.segments.remove(&room);
+        Ok(current)
+    }
+
+    pub async fn bootstrap_all(
+        &self,
+        rooms: Vec<Uuid>,
+    ) -> ChannelResult<HashMap<Uuid, i64>> {
+        let mut results = HashMap::with_capacity(rooms.len());
+        for room in rooms {
+            results.insert(room, self.bootstrap(room).await?);
+        }
+        Ok(results)
+    }
+
+    fn try_allocate(&self, room: &Uuid) -> Option<i64> {
+        let state = self.0.segments.get(room)?;
+        loop {
+            let current = state.next.load(Ordering::Acquire);
+            if current >= state.end {
+                return None;
+            }
+            if state
+                .next
+                .compare_exchange_weak(current, current + 1, Ordering::AcqRel, Ordering::Acquire)
+                .is_ok()
+            {
+                return Some(current);
+            }
+        }
+    }
+
+    fn get_refresh_lock(&self, room: Uuid) -> Arc<Mutex<()>> {
+        Arc::clone(
+            self.0
+                .refresh_locks
+                .entry(room)
+                .or_insert_with(|| Arc::new(Mutex::new(())))
+                .value(),
+        )
+    }
+
+    async fn refresh_segment(&self, room: Uuid) -> ChannelResult<()> {
+        let key = format!("{}{}", SEQ_KEY_PREFIX, room);
+        let cluster = require_cluster(&self.0.cache)?;
+        let mut conn = cluster.conn();
+
+        let counter: i64 = redis::Cmd::new()
+            .arg("INCRBY")
+            .arg(&key)
+            .arg(self.0.segment_size as i64)
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        let start = counter - self.0.segment_size as i64 + 1;
+        let end = counter + 1;
+
+        self.0.segments.insert(
+            room,
+            Arc::new(SegmentState {
+                end,
+                next: AtomicI64::new(start),
+            }),
+        );
+
+        Ok(())
+    }
+
+    async fn db_max_seq(&self, room: Uuid) -> ChannelResult<i64> {
+        let row: (i64,) = db::sqlx::query_as(
+            "SELECT COALESCE(MAX(seq), 0) FROM room_message WHERE room = $1 AND deleted_at IS NULL",
+        )
+        .bind(room)
+        .fetch_one(self.0.db.reader())
+        .await?;
+        Ok(row.0)
+    }
+}
diff --git a/lib/channel/token.rs b/lib/channel/token.rs
new file mode 100644
index 0000000..1ad4240
--- /dev/null
+++ b/lib/channel/token.rs
@@ -0,0 +1,306 @@
+use base64::Engine;
+use hmac::{KeyInit, Mac};
+use sha2::Sha256;
+use uuid::Uuid;
+
+use crate::{
+    ChannelBus, ChannelError, ChannelResult, security::require_cluster,
+};
+
+type HmacSha256 = hmac::Hmac<Sha256>;
+
+const VERSION: u8 = 0;
+pub const TOKEN_TTL_SECS: u64 = 600;
+const SESSION_TTL_SECS: u64 = 1800;
+const MAX_LIFETIME_SECS: i64 = 3000;
+
+const TOKEN_PREFIX: &str = "token:access:";
+const SESSION_PREFIX: &str = "channel:session:";
+
+const MAX_TOKEN_BASE64_LEN: usize = 256;
+
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
+pub struct ChannelAccessToken {
+    pub access_token: String,
+}
+
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
+pub struct ChannelTokenApply {
+    pub client_id: String,
+    pub device_id: String,
+}
+
+#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
+pub struct ChannelTokenContext {
+    pub user_id: Uuid,
+    pub device_id: String,
+    pub client_id: String,
+}
+
+struct TokenPayload {
+    user_id: Uuid,
+    created_at: i64,
+}
+
+impl TokenPayload {
+    const LEN: usize = 57;
+
+    fn encode(&self, signing_key: &[u8]) -> ChannelResult<Vec<u8>> {
+        let mut buf = Vec::with_capacity(Self::LEN);
+        buf.push(VERSION);
+        buf.extend_from_slice(self.user_id.as_bytes());
+        buf.extend_from_slice(&self.created_at.to_be_bytes());
+
+        let tag = hmac_sign(signing_key, &buf)?;
+        buf.extend_from_slice(&tag);
+
+        Ok(buf)
+    }
+
+    fn decode(bytes: &[u8], signing_key: &[u8]) -> ChannelResult<Self> {
+        if bytes.len() != Self::LEN || bytes[0] != VERSION {
+            return Err(ChannelError::TokenInvalidOrExpired);
+        }
+
+        let expected_tag = hmac_sign(signing_key, &bytes[..25])?;
+        if !constant_time_eq(&expected_tag, &bytes[25..]) {
+            return Err(ChannelError::TokenInvalidOrExpired);
+        }
+
+        let user_id_bytes: [u8; 16] = bytes[1..17].try_into().map_err(
+            |_: std::array::TryFromSliceError| {
+                ChannelError::TokenInvalidOrExpired
+            },
+        )?;
+        let user_id = Uuid::from_bytes(user_id_bytes);
+        let created_at_bytes: [u8; 8] = bytes[17..25].try_into().map_err(
+            |_: std::array::TryFromSliceError| {
+                ChannelError::TokenInvalidOrExpired
+            },
+        )?;
+        let created_at = i64::from_be_bytes(created_at_bytes);
+
+        Ok(TokenPayload {
+            user_id,
+            created_at,
+        })
+    }
+}
+
+impl ChannelBus {
+    fn signing_key(&self) -> ChannelResult<[u8; 32]> {
+        let secret =
+            self.inner.config.signing_secret.as_deref().ok_or(
+                ChannelError::Internal("no signing secret".to_string()),
+            )?;
+        let mut mac =
+            HmacSha256::new_from_slice(secret.as_bytes()).map_err(|_| {
+                ChannelError::Internal("hmac init failed".to_string())
+            })?;
+        mac.update(b"channel-access-token-signing-key");
+        let result = mac.finalize().into_bytes();
+        Ok(result.into())
+    }
+
+    fn session_hash_key(&self, user_id: &Uuid, created_at: i64) -> String {
+        format!("{}{}:{}", SESSION_PREFIX, user_id, created_at)
+    }
+
+    fn token_redis_key(&self, token_str: &str) -> String {
+        format!("{}{}", TOKEN_PREFIX, token_str)
+    }
+
+    pub async fn apply_access_token(
+        &self,
+        user_id: Uuid,
+        apply: ChannelTokenApply,
+    ) -> ChannelResult<ChannelAccessToken> {
+        let created_at = chrono::Utc::now().timestamp();
+        let signing_key = self.signing_key()?;
+
+        let payload = TokenPayload {
+            user_id,
+            created_at,
+        };
+        let token_bytes = payload.encode(&signing_key)?;
+        let access_token = base64::engine::general_purpose::URL_SAFE_NO_PAD
+            .encode(&token_bytes);
+
+        let session_key = self.session_hash_key(&user_id, created_at);
+        let token_key = self.token_redis_key(&access_token);
+
+        let cluster = require_cluster(&self.inner.cache)?;
+        let mut conn = cluster.conn();
+        let mut pipe = redis::Pipeline::new();
+        pipe.hset(&session_key, "device_id", &apply.device_id)
+            .hset(&session_key, "client_id", &apply.client_id)
+            .expire(&session_key, SESSION_TTL_SECS as i64);
+        pipe.query_async::<()>(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+        redis::Cmd::set_ex(&token_key, &session_key, TOKEN_TTL_SECS)
+            .query_async::<()>(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        Ok(ChannelAccessToken { access_token })
+    }
+
+    pub async fn check_access_token(
+        &self,
+        access_token: String,
+    ) -> ChannelResult<ChannelTokenContext> {
+        let token_bytes = decode_token_bytes(&access_token)?;
+
+        let signing_key = self.signing_key()?;
+        let payload = TokenPayload::decode(&token_bytes, &signing_key)?;
+
+        let elapsed = chrono::Utc::now().timestamp() - payload.created_at;
+        if elapsed > MAX_LIFETIME_SECS {
+            return Err(ChannelError::TokenInvalidOrExpired);
+        }
+
+        let session_key =
+            self.session_hash_key(&payload.user_id, payload.created_at);
+
+        let cluster = require_cluster(&self.inner.cache)?;
+        let mut conn = cluster.conn();
+
+        let token_key = self.token_redis_key(&access_token);
+        let token_exists: bool = redis::Cmd::new()
+            .arg("EXISTS")
+            .arg(&token_key)
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        if !token_exists {
+            return Err(ChannelError::TokenInvalidOrExpired);
+        }
+
+        let hash_data: std::collections::HashMap<String, String> =
+            redis::Cmd::new()
+                .arg("HGETALL")
+                .arg(&session_key)
+                .query_async(&mut conn)
+                .await
+                .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        let device_id = hash_data
+            .get("device_id")
+            .cloned()
+            .ok_or(ChannelError::TokenInvalidOrExpired)?;
+        let client_id = hash_data
+            .get("client_id")
+            .cloned()
+            .ok_or(ChannelError::TokenInvalidOrExpired)?;
+
+        Ok(ChannelTokenContext {
+            user_id: payload.user_id,
+            device_id,
+            client_id,
+        })
+    }
+
+    pub async fn renew_access_token(
+        &self,
+        access_token: String,
+    ) -> ChannelResult<ChannelAccessToken> {
+        let token_bytes = decode_token_bytes(&access_token)?;
+
+        let signing_key = self.signing_key()?;
+        let payload = TokenPayload::decode(&token_bytes, &signing_key)?;
+
+        let elapsed = chrono::Utc::now().timestamp() - payload.created_at;
+        if elapsed > MAX_LIFETIME_SECS {
+            return Err(ChannelError::RenewalLimitExceeded);
+        }
+
+        let session_key =
+            self.session_hash_key(&payload.user_id, payload.created_at);
+        let token_key = self.token_redis_key(&access_token);
+
+        let cluster = require_cluster(&self.inner.cache)?;
+        let mut conn = cluster.conn();
+        let hash_data: std::collections::HashMap<String, String> =
+            redis::Cmd::new()
+                .arg("HGETALL")
+                .arg(&session_key)
+                .query_async(&mut conn)
+                .await
+                .map_err(|e| {
+                    ChannelError::Cache(cache::CacheError::Redis(e))
+                })?;
+
+        let device_id = hash_data
+            .get("device_id")
+            .cloned()
+            .ok_or(ChannelError::TokenInvalidOrExpired)?;
+        let client_id = hash_data
+            .get("client_id")
+            .cloned()
+            .ok_or(ChannelError::TokenInvalidOrExpired)?;
+        let _: () = redis::Cmd::new()
+            .arg("DEL")
+            .arg(&token_key)
+            .query_async(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+        let created_at = chrono::Utc::now().timestamp();
+        let new_payload = TokenPayload {
+            user_id: payload.user_id,
+            created_at,
+        };
+        let new_token_bytes = new_payload.encode(&signing_key)?;
+        let new_access_token =
+            base64::engine::general_purpose::URL_SAFE_NO_PAD
+                .encode(&new_token_bytes);
+
+        let new_session_key =
+            self.session_hash_key(&payload.user_id, created_at);
+        let new_token_key = self.token_redis_key(&new_access_token);
+        let mut pipe = redis::Pipeline::new();
+        pipe.hset(&new_session_key, "device_id", &device_id)
+            .hset(&new_session_key, "client_id", &client_id)
+            .expire(&new_session_key, SESSION_TTL_SECS as i64);
+
+        pipe.query_async::<()>(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+        redis::Cmd::set_ex(&new_token_key, &new_session_key, TOKEN_TTL_SECS)
+            .query_async::<()>(&mut conn)
+            .await
+            .map_err(|e| ChannelError::Cache(cache::CacheError::Redis(e)))?;
+
+        Ok(ChannelAccessToken {
+            access_token: new_access_token,
+        })
+    }
+}
+
+fn decode_token_bytes(token: &str) -> ChannelResult<Vec<u8>> {
+    if token.len() > MAX_TOKEN_BASE64_LEN {
+        return Err(ChannelError::TokenInvalidOrExpired);
+    }
+    base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(token)
+        .map_err(|_| ChannelError::TokenInvalidOrExpired)
+}
+
+fn hmac_sign(key: &[u8], payload: &[u8]) -> ChannelResult<[u8; 32]> {
+    let mut mac = HmacSha256::new_from_slice(key)
+        .map_err(|_| ChannelError::Internal("hmac sign failed".to_string()))?;
+    mac.update(payload);
+    Ok(mac.finalize().into_bytes().into())
+}
+
+fn constant_time_eq(expected: &[u8; 32], actual: &[u8]) -> bool {
+    if actual.len() != 32 {
+        return false;
+    }
+    let mut diff = 0u8;
+    for i in 0..32 {
+        diff |= expected[i] ^ actual[i];
+    }
+    diff == 0
+}
diff --git a/lib/config/Cargo.toml b/lib/config/Cargo.toml
new file mode 100644
index 0000000..7a44b88
--- /dev/null
+++ b/lib/config/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "config"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+[lib]
+path = "lib.rs"
+name = "config"
+[dependencies]
+dotenvy = { workspace = true }
+anyhow = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+uuid = { workspace = true, features = ["v4"] }
+num_cpus = { workspace = true }
+tracing = { workspace = true }
+[lints]
+workspace = true
diff --git a/lib/config/ai.rs b/lib/config/ai.rs
new file mode 100644
index 0000000..e646bb7
--- /dev/null
+++ b/lib/config/ai.rs
@@ -0,0 +1,16 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn ai_basic_url(&self) -> anyhow::Result<String> {
+        if let Some(url) = self.env.get("APP_AI_BASIC_URL") {
+            return Ok(url.to_string());
+        }
+        Err(anyhow::anyhow!("APP_AI_BASIC_URL not found"))
+    }
+    pub fn ai_api_key(&self) -> anyhow::Result<String> {
+        if let Some(api_key) = self.env.get("APP_AI_API_KEY") {
+            return Ok(api_key.to_string());
+        }
+        Err(anyhow::anyhow!("APP_AI_API_KEY not found"))
+    }
+}
diff --git a/lib/config/app.rs b/lib/config/app.rs
new file mode 100644
index 0000000..0335865
--- /dev/null
+++ b/lib/config/app.rs
@@ -0,0 +1,37 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn app_name(&self) -> anyhow::Result<String> {
+        if let Some(name) = self.env.get("APP_NAME") {
+            return Ok(name.to_string());
+        }
+        Ok(env!("CARGO_PKG_NAME").to_string())
+    }
+
+    pub fn app_version(&self) -> anyhow::Result<String> {
+        if let Some(version) = self.env.get("APP_VERSION") {
+            return Ok(version.to_string());
+        }
+        Ok(env!("CARGO_PKG_VERSION").to_string())
+    }
+    pub fn app_description(&self) -> anyhow::Result<String> {
+        if let Some(description) = self.env.get("APP_DESCRIPTION") {
+            return Ok(description.to_string());
+        }
+        Ok(env!("CARGO_PKG_DESCRIPTION").to_string())
+    }
+
+    pub fn api_port(&self) -> anyhow::Result<u16> {
+        if let Some(port) = self.env.get("APP_API_PORT") {
+            return Ok(port.parse::<u16>()?);
+        }
+        Ok(8080)
+    }
+
+    pub fn session_secret(&self) -> anyhow::Result<String> {
+        if let Some(secret) = self.env.get("APP_SESSION_SECRET") {
+            return Ok(secret.to_string());
+        }
+        Err(anyhow::anyhow!("APP_SESSION_SECRET not found"))
+    }
+}
diff --git a/lib/config/auth.rs b/lib/config/auth.rs
new file mode 100644
index 0000000..d800763
--- /dev/null
+++ b/lib/config/auth.rs
@@ -0,0 +1,19 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn auth_rotation_interval(&self) -> anyhow::Result<u64> {
+        self.parse_env("APP_AUTH_ROTATION_INTERVAL_SECONDS", 10800)
+    }
+
+    pub fn auth_key_ttl(&self) -> anyhow::Result<u64> {
+        self.parse_env("APP_AUTH_KEY_TTL_SECONDS", 2_592_000)
+    }
+
+    pub fn auth_session_ttl(&self) -> anyhow::Result<u64> {
+        self.parse_env("APP_AUTH_SESSION_TTL_SECONDS", 2_592_000)
+    }
+
+    pub fn auth_token_ttl(&self) -> anyhow::Result<u64> {
+        self.parse_env("APP_AUTH_TOKEN_TTL_SECONDS", 21_600)
+    }
+}
diff --git a/lib/config/avatar.rs b/lib/config/avatar.rs
new file mode 100644
index 0000000..efe2bb9
--- /dev/null
+++ b/lib/config/avatar.rs
@@ -0,0 +1,10 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn avatar_path(&self) -> anyhow::Result<String> {
+        if let Some(url) = self.env.get("APP_AVATAR_PATH") {
+            return Ok(url.to_string());
+        }
+        Err(anyhow::anyhow!("APP_AVATAR_PATH not found"))
+    }
+}
diff --git a/lib/config/cache.rs b/lib/config/cache.rs
new file mode 100644
index 0000000..eee340a
--- /dev/null
+++ b/lib/config/cache.rs
@@ -0,0 +1,83 @@
+use std::time::Duration;
+
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn cache_local_max_capacity(&self) -> anyhow::Result<u64> {
+        self.parse_env("APP_CACHE_LOCAL_MAX_CAPACITY", 10_000)
+    }
+
+    pub fn cache_local_ttl(&self) -> anyhow::Result<Option<Duration>> {
+        self.parse_optional_duration_secs(
+            "APP_CACHE_LOCAL_TTL_SECONDS",
+            Some(300),
+        )
+    }
+
+    pub fn cache_local_tti(&self) -> anyhow::Result<Option<Duration>> {
+        self.parse_optional_duration_secs("APP_CACHE_LOCAL_TTI_SECONDS", None)
+    }
+
+    pub fn cache_default_ttl(&self) -> anyhow::Result<Option<Duration>> {
+        self.parse_optional_duration_secs(
+            "APP_CACHE_DEFAULT_TTL_SECONDS",
+            Some(300),
+        )
+    }
+
+    pub fn cache_cluster_enabled(&self) -> anyhow::Result<bool> {
+        self.parse_env("APP_CACHE_CLUSTER_ENABLED", false)
+    }
+
+    pub fn cache_cluster_key_prefix(&self) -> Option<String> {
+        self.env
+            .get("APP_CACHE_CLUSTER_KEY_PREFIX")
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    pub fn cache_cluster_command_timeout(&self) -> anyhow::Result<Duration> {
+        self.parse_duration_secs("APP_CACHE_CLUSTER_COMMAND_TIMEOUT_SECONDS", 3)
+    }
+
+    pub fn cache_cluster_write_through(&self) -> anyhow::Result<bool> {
+        self.parse_env("APP_CACHE_CLUSTER_WRITE_THROUGH", true)
+    }
+
+    pub(crate) fn parse_env<T>(
+        &self,
+        key: &str,
+        default: T,
+    ) -> anyhow::Result<T>
+    where
+        T: std::str::FromStr,
+        T::Err: std::error::Error + Send + Sync + 'static,
+    {
+        match self.env.get(key).map(|value| value.trim()) {
+            Some(value) if !value.is_empty() => Ok(value.parse::<T>()?),
+            _ => Ok(default),
+        }
+    }
+
+    pub(crate) fn parse_duration_secs(
+        &self,
+        key: &str,
+        default_secs: u64,
+    ) -> anyhow::Result<Duration> {
+        Ok(Duration::from_secs(self.parse_env(key, default_secs)?))
+    }
+
+    pub(crate) fn parse_optional_duration_secs(
+        &self,
+        key: &str,
+        default_secs: Option<u64>,
+    ) -> anyhow::Result<Option<Duration>> {
+        match self.env.get(key).map(|value| value.trim()) {
+            Some("0") => Ok(None),
+            Some(value) if !value.is_empty() => {
+                Ok(Some(Duration::from_secs(value.parse()?)))
+            }
+            _ => Ok(default_secs.map(Duration::from_secs)),
+        }
+    }
+}
diff --git a/lib/config/database.rs b/lib/config/database.rs
new file mode 100644
index 0000000..6409e19
--- /dev/null
+++ b/lib/config/database.rs
@@ -0,0 +1,83 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn database_url(&self) -> anyhow::Result<String> {
+        if let Some(url) = self.env.get("APP_DATABASE_URL") {
+            return Ok(url.to_string());
+        }
+        Err(anyhow::anyhow!("APP_DATABASE_URL not found"))
+    }
+    pub fn database_max_connections(&self) -> anyhow::Result<u32> {
+        if let Some(max_connections) =
+            self.env.get("APP_DATABASE_MAX_CONNECTIONS")
+        {
+            return Ok(max_connections.parse::<u32>()?);
+        }
+        Ok(10)
+    }
+    pub fn database_min_connections(&self) -> anyhow::Result<u32> {
+        if let Some(min_connections) =
+            self.env.get("APP_DATABASE_MIN_CONNECTIONS")
+        {
+            return Ok(min_connections.parse::<u32>()?);
+        }
+        Ok(2)
+    }
+    pub fn database_idle_timeout(&self) -> anyhow::Result<u64> {
+        if let Some(idle_timeout) = self.env.get("APP_DATABASE_IDLE_TIMEOUT") {
+            return Ok(idle_timeout.parse::<u64>()?);
+        }
+        Ok(600) // seconds
+    }
+    pub fn database_max_lifetime(&self) -> anyhow::Result<u64> {
+        if let Some(max_lifetime) = self.env.get("APP_DATABASE_MAX_LIFETIME") {
+            return Ok(max_lifetime.parse::<u64>()?);
+        }
+        Ok(3600) // seconds
+    }
+    pub fn database_connection_timeout(&self) -> anyhow::Result<u64> {
+        if let Some(connection_timeout) =
+            self.env.get("APP_DATABASE_CONNECTION_TIMEOUT")
+        {
+            return Ok(connection_timeout.parse::<u64>()?);
+        }
+        Ok(8) // seconds
+    }
+    pub fn database_schema_search_path(&self) -> anyhow::Result<String> {
+        if let Some(schema_search_path) =
+            self.env.get("APP_DATABASE_SCHEMA_SEARCH_PATH")
+        {
+            return Ok(schema_search_path.to_string());
+        }
+        Ok("public".to_string())
+    }
+    pub fn database_read_replicas(&self) -> anyhow::Result<Option<String>> {
+        if let Some(replicas) = self.env.get("APP_DATABASE_REPLICAS") {
+            if replicas.is_empty() {
+                return Ok(None);
+            }
+            return Ok(Some(replicas.to_string()));
+        }
+        Ok(None)
+    }
+    pub fn database_health_check_interval(&self) -> anyhow::Result<u64> {
+        if let Some(interval) =
+            self.env.get("APP_DATABASE_HEALTH_CHECK_INTERVAL")
+        {
+            return Ok(interval.parse::<u64>()?);
+        }
+        Ok(30)
+    }
+    pub fn database_retry_attempts(&self) -> anyhow::Result<u32> {
+        if let Some(attempts) = self.env.get("APP_DATABASE_RETRY_ATTEMPTS") {
+            return Ok(attempts.parse::<u32>()?);
+        }
+        Ok(3)
+    }
+    pub fn database_retry_delay(&self) -> anyhow::Result<u64> {
+        if let Some(delay) = self.env.get("APP_DATABASE_RETRY_DELAY") {
+            return Ok(delay.parse::<u64>()?);
+        }
+        Ok(5)
+    }
+}
diff --git a/lib/config/domain.rs b/lib/config/domain.rs
new file mode 100644
index 0000000..702d272
--- /dev/null
+++ b/lib/config/domain.rs
@@ -0,0 +1,29 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn main_domain(&self) -> anyhow::Result<String> {
+        if let Some(domain_url) = self.env.get("APP_DOMAIN_URL") {
+            return Ok(domain_url.to_string());
+        }
+        Ok("http://127.0.0.1".to_string())
+    }
+
+    pub fn static_domain(&self) -> anyhow::Result<String> {
+        if let Some(static_domain) = self.env.get("APP_STATIC_DOMAIN") {
+            return Ok(static_domain.to_string());
+        }
+        self.main_domain()
+    }
+    pub fn media_domain(&self) -> anyhow::Result<String> {
+        if let Some(media_domain) = self.env.get("APP_MEDIA_DOMAIN") {
+            return Ok(media_domain.to_string());
+        }
+        self.main_domain()
+    }
+    pub fn git_http_domain(&self) -> anyhow::Result<String> {
+        if let Some(git_http_domain) = self.env.get("APP_GIT_HTTP_DOMAIN") {
+            return Ok(git_http_domain.to_string());
+        }
+        self.main_domain()
+    }
+}
diff --git a/lib/config/embed.rs b/lib/config/embed.rs
new file mode 100644
index 0000000..8a816b4
--- /dev/null
+++ b/lib/config/embed.rs
@@ -0,0 +1,37 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn get_embed_model_base_url(&self) -> anyhow::Result<String> {
+        if let Some(url) = self.env.get("APP_EMBED_MODEL_BASE_URL") {
+            return Ok(url.to_string());
+        }
+        Err(anyhow::anyhow!("APP_EMBED_MODEL_BASE_URL not found"))
+    }
+    pub fn get_embed_model_dimensions(&self) -> anyhow::Result<u64> {
+        if let Some(dimensions) = self.env.get("APP_EMBED_MODEL_DIMENSIONS") {
+            return Ok(dimensions.parse::<u64>()?);
+        }
+        Err(anyhow::anyhow!("APP_EMBED_MODEL_DIMENSIONS not found"))
+    }
+    pub fn get_embed_model_api_key(&self) -> anyhow::Result<String> {
+        if let Some(api_key) = self.env.get("APP_EMBED_MODEL_API_KEY") {
+            return Ok(api_key.to_string());
+        }
+        Err(anyhow::anyhow!("APP_EMBED_MODEL_API_KEY not found"))
+    }
+    pub fn get_embed_model_name(&self) -> anyhow::Result<String> {
+        if let Some(model_name) = self.env.get("APP_EMBED_MODEL_NAME") {
+            return Ok(model_name.to_string());
+        }
+        Err(anyhow::anyhow!("APP_EMBED_MODEL_NAME not found"))
+    }
+    pub fn get_qdrant_url(&self) -> anyhow::Result<String> {
+        if let Some(url) = self.env.get("APP_QDRANT_URL") {
+            return Ok(url.to_string());
+        }
+        Err(anyhow::anyhow!("APP_QDRANT_URL not found"))
+    }
+    pub fn get_qdrant_api_key(&self) -> Option<String> {
+        self.env.get("APP_QDRANT_API_KEY").map(|s| s.to_string())
+    }
+}
diff --git a/lib/config/git.rs b/lib/config/git.rs
new file mode 100644
index 0000000..c6f05a5
--- /dev/null
+++ b/lib/config/git.rs
@@ -0,0 +1,39 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn git_http_port(&self) -> anyhow::Result<u16> {
+        if let Some(port) = self.env.get("APP_GIT_HTTP_PORT") {
+            return Ok(port.parse::<u16>()?);
+        }
+        Ok(8021)
+    }
+
+    pub fn git_rpc_port(&self) -> anyhow::Result<u16> {
+        if let Some(port) = self.env.get("APP_GIT_RPC_PORT") {
+            return Ok(port.parse::<u16>()?);
+        }
+        Ok(8030)
+    }
+
+    pub fn git_rpc_addr(&self) -> anyhow::Result<String> {
+        self.env
+            .get("APP_GIT_RPC_ADDR")
+            .map(|v| v.trim().to_string())
+            .ok_or_else(|| anyhow::anyhow!("APP_GIT_RPC_ADDR not set"))
+    }
+
+    pub fn repos_root(&self) -> anyhow::Result<String> {
+        if let Some(root) = self.env.get("APP_REPOS_ROOT") {
+            return Ok(root.to_string());
+        }
+        let base = std::env::current_dir()?;
+        Ok(base.join("data").join("repos").to_string_lossy().to_string())
+    }
+
+    pub fn gitsync_health_port(&self) -> u16 {
+        self.env
+            .get("APP_GITSYNC_HEALTH_PORT")
+            .and_then(|v| v.trim().parse::<u16>().ok())
+            .unwrap_or(8083)
+    }
+}
diff --git a/lib/config/hook.rs b/lib/config/hook.rs
new file mode 100644
index 0000000..4056bbc
--- /dev/null
+++ b/lib/config/hook.rs
@@ -0,0 +1,84 @@
+use serde::{Deserialize, Serialize};
+
+use crate::AppConfig;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PoolConfig {
+    pub max_concurrent: usize,
+    pub cpu_threshold: f32,
+    pub redis_list_prefix: String,
+    pub redis_log_channel: String,
+    pub redis_block_timeout_secs: u64,
+    pub redis_max_retries: usize,
+    pub worker_id: String,
+}
+
+impl PoolConfig {
+    pub fn from_env(config: &AppConfig) -> Self {
+        let max_concurrent = config
+            .env
+            .get("HOOK_POOL_MAX_CONCURRENT")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or_else(num_cpus::get);
+
+        let cpu_threshold = config
+            .env
+            .get("HOOK_POOL_CPU_THRESHOLD")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(80.0);
+
+        let redis_list_prefix = config
+            .env
+            .get("HOOK_POOL_REDIS_LIST_PREFIX")
+            .cloned()
+            .unwrap_or_else(|| "{hook}".to_string());
+
+        let redis_log_channel = config
+            .env
+            .get("HOOK_POOL_REDIS_LOG_CHANNEL")
+            .cloned()
+            .unwrap_or_else(|| "hook:logs".to_string());
+
+        let redis_block_timeout_secs = config
+            .env
+            .get("HOOK_POOL_REDIS_BLOCK_TIMEOUT")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(5);
+
+        let redis_max_retries = config
+            .env
+            .get("HOOK_POOL_REDIS_MAX_RETRIES")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(3);
+
+        let worker_id = config
+            .env
+            .get("HOOK_POOL_WORKER_ID")
+            .cloned()
+            .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
+
+        Self {
+            max_concurrent,
+            cpu_threshold,
+            redis_list_prefix,
+            redis_log_channel,
+            redis_block_timeout_secs,
+            redis_max_retries,
+            worker_id,
+        }
+    }
+}
+
+impl Default for PoolConfig {
+    fn default() -> Self {
+        Self {
+            max_concurrent: num_cpus::get(),
+            cpu_threshold: 80.0,
+            redis_list_prefix: "{hook}".to_string(),
+            redis_log_channel: "hook:logs".to_string(),
+            redis_block_timeout_secs: 5,
+            redis_max_retries: 3,
+            worker_id: uuid::Uuid::new_v4().to_string(),
+        }
+    }
+}
diff --git a/lib/config/lib.rs b/lib/config/lib.rs
new file mode 100644
index 0000000..0d2598a
--- /dev/null
+++ b/lib/config/lib.rs
@@ -0,0 +1,58 @@
+use std::{collections::HashMap, sync::OnceLock};
+
+pub static GLOBAL_CONFIG: OnceLock<AppConfig> = OnceLock::new();
+
+#[derive(Clone, Debug)]
+pub struct AppConfig {
+    pub env: HashMap<String, String>,
+}
+
+impl AppConfig {
+    const ENV_FILES: &'static [&'static str] = &[".env", ".env.local"];
+    pub fn load() -> AppConfig {
+        let mut env = HashMap::new();
+        for env_file in AppConfig::ENV_FILES {
+            if let Err(e) = dotenvy::from_path(env_file) {
+                tracing::debug!(file = %env_file, error = %e, "dotenv load skipped");
+            }
+            if let Ok(env_file_content) = std::fs::read_to_string(env_file) {
+                for line in env_file_content.lines() {
+                    if let Some((key, value)) = line.split_once('=') {
+                        env.insert(key.to_string(), value.to_string());
+                    }
+                }
+            }
+        }
+        env = env.into_iter().chain(std::env::vars()).collect();
+        let this = AppConfig { env };
+        if GLOBAL_CONFIG.get().is_some() {
+            GLOBAL_CONFIG.get().unwrap().clone()
+        } else {
+            let _ = GLOBAL_CONFIG.set(this);
+            GLOBAL_CONFIG
+                .get()
+                .expect("global config should be set after load")
+                .clone()
+        }
+    }
+}
+
+pub mod ai;
+pub mod app;
+pub mod auth;
+pub mod avatar;
+pub mod cache;
+pub mod database;
+pub mod domain;
+pub mod embed;
+pub mod git;
+pub mod hook;
+pub mod logs;
+pub mod nats;
+pub mod oauth;
+pub mod pull_request;
+pub mod qdrant;
+pub mod redis;
+pub mod smtp;
+pub mod ssh;
+pub mod storage;
diff --git a/lib/config/logs.rs b/lib/config/logs.rs
new file mode 100644
index 0000000..b3e5b98
--- /dev/null
+++ b/lib/config/logs.rs
@@ -0,0 +1,95 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn log_level(&self) -> anyhow::Result<String> {
+        if let Some(level) = self.env.get("APP_LOG_LEVEL") {
+            return Ok(level.to_string());
+        }
+        Ok("info".to_string())
+    }
+
+    pub fn log_format(&self) -> anyhow::Result<String> {
+        if let Some(format) = self.env.get("APP_LOG_FORMAT") {
+            return Ok(format.to_string());
+        }
+        Ok("json".to_string())
+    }
+
+    pub fn log_file_enabled(&self) -> anyhow::Result<bool> {
+        if let Some(enabled) = self.env.get("APP_LOG_FILE_ENABLED") {
+            return Ok(enabled.parse::<bool>()?);
+        }
+        Ok(false)
+    }
+
+    pub fn log_file_path(&self) -> anyhow::Result<String> {
+        if let Some(path) = self.env.get("APP_LOG_FILE_PATH") {
+            return Ok(path.to_string());
+        }
+        Ok("./logs".to_string())
+    }
+
+    pub fn log_file_rotation(&self) -> anyhow::Result<String> {
+        if let Some(rotation) = self.env.get("APP_LOG_FILE_ROTATION") {
+            return Ok(rotation.to_string());
+        }
+        Ok("daily".to_string())
+    }
+
+    pub fn log_file_max_files(&self) -> anyhow::Result<usize> {
+        if let Some(max_files) = self.env.get("APP_LOG_FILE_MAX_FILES") {
+            return Ok(max_files.parse::<usize>()?);
+        }
+        Ok(7)
+    }
+
+    pub fn log_file_max_size(&self) -> anyhow::Result<usize> {
+        if let Some(max_size) = self.env.get("APP_LOG_FILE_MAX_SIZE") {
+            return Ok(max_size.parse::<usize>()?);
+        }
+        Ok(104857600) // 100MB
+    }
+
+    pub fn otel_enabled(&self) -> anyhow::Result<bool> {
+        if let Some(enabled) = self.env.get("APP_OTEL_ENABLED") {
+            return Ok(enabled.parse::<bool>()?);
+        }
+        Ok(false)
+    }
+
+    pub fn otel_endpoint(&self) -> anyhow::Result<String> {
+        if let Some(endpoint) = self.env.get("APP_OTEL_ENDPOINT") {
+            return Ok(endpoint.to_string());
+        }
+        Ok("http://localhost:5080/api/default/v1/traces".to_string())
+    }
+
+    pub fn otel_service_name(&self) -> anyhow::Result<String> {
+        if let Some(service_name) = self.env.get("APP_OTEL_SERVICE_NAME") {
+            return Ok(service_name.to_string());
+        }
+        Ok(env!("CARGO_PKG_NAME").to_string())
+    }
+
+    pub fn otel_service_version(&self) -> anyhow::Result<String> {
+        if let Some(service_version) = self.env.get("APP_OTEL_SERVICE_VERSION")
+        {
+            return Ok(service_version.to_string());
+        }
+        Ok(env!("CARGO_PKG_VERSION").to_string())
+    }
+
+    pub fn otel_authorization(&self) -> anyhow::Result<Option<String>> {
+        if let Some(authorization) = self.env.get("APP_OTEL_AUTHORIZATION") {
+            return Ok(Some(authorization.to_string()));
+        }
+        Ok(None)
+    }
+
+    pub fn otel_organization(&self) -> anyhow::Result<Option<String>> {
+        if let Some(organization) = self.env.get("APP_OTEL_ORGANIZATION") {
+            return Ok(Some(organization.to_string()));
+        }
+        Ok(None)
+    }
+}
diff --git a/lib/config/nats.rs b/lib/config/nats.rs
new file mode 100644
index 0000000..a2e2233
--- /dev/null
+++ b/lib/config/nats.rs
@@ -0,0 +1,83 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn nats_url(&self) -> String {
+        self.env
+            .get("NATS_URL")
+            .cloned()
+            .unwrap_or_else(|| "localhost:4222".to_string())
+    }
+
+    pub fn nats_token(&self) -> Option<String> {
+        self.env.get("NATS_TOKEN").cloned()
+    }
+
+    pub fn nats_stream_name(&self) -> String {
+        self.env
+            .get("NATS_STREAM_NAME")
+            .cloned()
+            .unwrap_or_else(|| "APP_EVENTS".to_string())
+    }
+
+    pub fn nats_stream_subjects(&self) -> Vec<String> {
+        self.env
+            .get("NATS_STREAM_SUBJECTS")
+            .map(|subjects| {
+                subjects
+                    .split(',')
+                    .map(str::trim)
+                    .filter(|subject| !subject.is_empty())
+                    .map(ToOwned::to_owned)
+                    .collect()
+            })
+            .filter(|subjects: &Vec<String>| !subjects.is_empty())
+            .unwrap_or_else(|| {
+                let subject = self
+                    .env
+                    .get("APP_EMAIL_TOPIC")
+                    .or_else(|| self.env.get("EMAIL_TOPIC"))
+                    .cloned()
+                    .unwrap_or_else(|| "email.send".to_string());
+                vec![subject.clone(), format!("{subject}.>")]
+            })
+    }
+
+    pub fn nats_max_deliver(&self) -> i64 {
+        self.env
+            .get("NATS_MAX_DELIVER")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(3)
+    }
+
+    pub fn nats_ack_wait_secs(&self) -> u64 {
+        self.env
+            .get("NATS_ACK_WAIT_SECS")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(10)
+    }
+
+    pub fn nats_retry_delay_secs(&self) -> u64 {
+        self.env
+            .get("NATS_RETRY_DELAY_SECS")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or_else(|| self.nats_ack_wait_secs())
+    }
+
+    pub fn nats_max_age_secs(&self) -> u64 {
+        self.env
+            .get("NATS_MAX_AGE_SECS")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(86_400)
+    }
+
+    pub fn nats_buffer_size(&self) -> usize {
+        self.env
+            .get("NATS_BUFFER_SIZE")
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(256)
+    }
+
+    pub fn nats_is_enabled(&self) -> bool {
+        !self.nats_url().is_empty()
+    }
+}
diff --git a/lib/config/oauth.rs b/lib/config/oauth.rs
new file mode 100644
index 0000000..d58f749
--- /dev/null
+++ b/lib/config/oauth.rs
@@ -0,0 +1,7 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn oauth_server_port(&self) -> anyhow::Result<u16> {
+        self.parse_env("APP_OAUTH_SERVER_PORT", 8082)
+    }
+}
diff --git a/lib/config/pull_request.rs b/lib/config/pull_request.rs
new file mode 100644
index 0000000..fd82ea0
--- /dev/null
+++ b/lib/config/pull_request.rs
@@ -0,0 +1,24 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn pr_rpc_addr(&self) -> anyhow::Result<String> {
+        self.env
+            .get("APP_PR_RPC_ADDR")
+            .map(|v| v.trim().to_string())
+            .ok_or_else(|| anyhow::anyhow!("APP_PR_RPC_ADDR not set"))
+    }
+
+    pub fn pr_rpc_port(&self) -> anyhow::Result<u16> {
+        if let Some(port) = self.env.get("APP_PR_RPC_PORT") {
+            return Ok(port.parse::<u16>()?);
+        }
+        Ok(8040)
+    }
+
+    pub fn pr_http_port(&self) -> anyhow::Result<u16> {
+        if let Some(port) = self.env.get("APP_PR_HTTP_PORT") {
+            return Ok(port.parse::<u16>()?);
+        }
+        Ok(8041)
+    }
+}
diff --git a/lib/config/qdrant.rs b/lib/config/qdrant.rs
new file mode 100644
index 0000000..a507f08
--- /dev/null
+++ b/lib/config/qdrant.rs
@@ -0,0 +1,17 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn qdrant_url(&self) -> anyhow::Result<String> {
+        if let Some(url) = self.env.get("APP_QDRANT_URL") {
+            return Ok(url.to_string());
+        }
+        Err(anyhow::anyhow!("APP_QDRANT_URL not found"))
+    }
+
+    pub fn qdrant_api_key(&self) -> anyhow::Result<Option<String>> {
+        if let Some(api_key) = self.env.get("APP_QDRANT_API_KEY") {
+            return Ok(Some(api_key.to_string()));
+        }
+        Ok(None)
+    }
+}
diff --git a/lib/config/redis.rs b/lib/config/redis.rs
new file mode 100644
index 0000000..ca44d89
--- /dev/null
+++ b/lib/config/redis.rs
@@ -0,0 +1,41 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn redis_url(&self) -> anyhow::Result<String> {
+        let urls = self.redis_urls()?;
+        urls.into_iter().next().ok_or_else(|| {
+            anyhow::anyhow!("APP_REDIS_URLS or APP_REDIS_URL is empty")
+        })
+    }
+
+    pub fn redis_urls(&self) -> anyhow::Result<Vec<String>> {
+        if let Some(urls) = self.env.get("APP_REDIS_URLS") {
+            return Ok(urls.split(',').map(|s| s.trim().to_string()).collect());
+        }
+        if let Some(url) = self.env.get("APP_REDIS_URL") {
+            return Ok(vec![url.to_string()]);
+        }
+        Err(anyhow::anyhow!("APP_REDIS_URLS or APP_REDIS_URL not found"))
+    }
+
+    pub fn redis_pool_size(&self) -> anyhow::Result<u32> {
+        if let Some(pool_size) = self.env.get("APP_REDIS_POOL_SIZE") {
+            return Ok(pool_size.parse::<u32>()?);
+        }
+        Ok(10)
+    }
+
+    pub fn redis_connect_timeout(&self) -> anyhow::Result<u64> {
+        if let Some(timeout) = self.env.get("APP_REDIS_CONNECT_TIMEOUT") {
+            return Ok(timeout.parse::<u64>()?);
+        }
+        Ok(5)
+    }
+
+    pub fn redis_acquire_timeout(&self) -> anyhow::Result<u64> {
+        if let Some(timeout) = self.env.get("APP_REDIS_ACQUIRE_TIMEOUT") {
+            return Ok(timeout.parse::<u64>()?);
+        }
+        Ok(5)
+    }
+}
diff --git a/lib/config/smtp.rs b/lib/config/smtp.rs
new file mode 100644
index 0000000..12ee602
--- /dev/null
+++ b/lib/config/smtp.rs
@@ -0,0 +1,84 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn smtp_host(&self) -> anyhow::Result<String> {
+        if let Some(host) = self.env.get("APP_SMTP_HOST") {
+            return Ok(host.to_string());
+        }
+        Err(anyhow::anyhow!("APP_SMTP_HOST not found"))
+    }
+
+    pub fn smtp_port(&self) -> anyhow::Result<u16> {
+        if let Some(port) = self.env.get("APP_SMTP_PORT") {
+            return Ok(port.parse::<u16>()?);
+        }
+        Ok(587)
+    }
+
+    pub fn smtp_username(&self) -> anyhow::Result<String> {
+        if let Some(username) = self.env.get("APP_SMTP_USERNAME") {
+            return Ok(username.to_string());
+        }
+        Err(anyhow::anyhow!("APP_SMTP_USERNAME not found"))
+    }
+
+    pub fn smtp_password(&self) -> anyhow::Result<String> {
+        if let Some(password) = self.env.get("APP_SMTP_PASSWORD") {
+            return Ok(password.to_string());
+        }
+        Err(anyhow::anyhow!("APP_SMTP_PASSWORD not found"))
+    }
+
+    pub fn smtp_from(&self) -> anyhow::Result<String> {
+        if let Some(from) = self.env.get("APP_SMTP_FROM") {
+            return Ok(from.to_string());
+        }
+        Err(anyhow::anyhow!("APP_SMTP_FROM not found"))
+    }
+
+    pub fn smtp_tls(&self) -> anyhow::Result<bool> {
+        if let Some(tls) = self.env.get("APP_SMTP_TLS") {
+            return Ok(tls.parse::<bool>()?);
+        }
+        Ok(true)
+    }
+
+    pub fn smtp_timeout(&self) -> anyhow::Result<u64> {
+        if let Some(timeout) = self.env.get("APP_SMTP_TIMEOUT") {
+            return Ok(timeout.parse::<u64>()?);
+        }
+        Ok(30)
+    }
+
+    pub fn email_topic(&self) -> String {
+        self.env
+            .get("APP_EMAIL_TOPIC")
+            .or_else(|| self.env.get("EMAIL_TOPIC"))
+            .cloned()
+            .unwrap_or_else(|| "email.send".to_string())
+    }
+
+    pub fn email_consumer_group_id(&self) -> String {
+        self.env
+            .get("APP_EMAIL_CONSUMER_GROUP_ID")
+            .or_else(|| self.env.get("EMAIL_CONSUMER_GROUP_ID"))
+            .cloned()
+            .unwrap_or_else(|| "email-service".to_string())
+    }
+
+    pub fn email_send_retry_attempts(&self) -> u32 {
+        self.env
+            .get("APP_EMAIL_SEND_RETRY_ATTEMPTS")
+            .or_else(|| self.env.get("EMAIL_SEND_RETRY_ATTEMPTS"))
+            .and_then(|value| value.parse().ok())
+            .unwrap_or(3)
+    }
+
+    pub fn email_send_retry_base_delay_secs(&self) -> u64 {
+        self.env
+            .get("APP_EMAIL_SEND_RETRY_BASE_DELAY_SECS")
+            .or_else(|| self.env.get("EMAIL_SEND_RETRY_BASE_DELAY_SECS"))
+            .and_then(|value| value.parse().ok())
+            .unwrap_or(1)
+    }
+}
diff --git a/lib/config/ssh.rs b/lib/config/ssh.rs
new file mode 100644
index 0000000..73d755e
--- /dev/null
+++ b/lib/config/ssh.rs
@@ -0,0 +1,38 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn ssh_domain(&self) -> anyhow::Result<String> {
+        if let Some(ssh_domain) = self.env.get("APP_SSH_DOMAIN") {
+            return Ok(ssh_domain.to_string());
+        }
+        let main_domain = self.main_domain()?;
+        if let Some(stripped) = main_domain.strip_prefix("https://") {
+            Ok(stripped.to_string())
+        } else if let Some(stripped) = main_domain.strip_prefix("http://") {
+            Ok(stripped.to_string())
+        } else {
+            Ok(main_domain)
+        }
+    }
+
+    pub fn ssh_port(&self) -> anyhow::Result<u16> {
+        if let Some(ssh_port) = self.env.get("APP_SSH_PORT") {
+            return Ok(ssh_port.parse::<u16>()?);
+        }
+        Ok(8022)
+    }
+
+    pub fn ssh_server_private_key_file(&self) -> anyhow::Result<String> {
+        if let Some(path) = self.env.get("APP_SSH_SERVER_PRIVATE_KEY_FILE") {
+            return Ok(path.to_string());
+        }
+        Ok("".to_string())
+    }
+
+    pub fn ssh_server_public_key_file(&self) -> anyhow::Result<String> {
+        if let Some(path) = self.env.get("APP_SSH_SERVER_PUBLIC_KEY_FILE") {
+            return Ok(path.to_string());
+        }
+        Ok("".to_string())
+    }
+}
diff --git a/lib/config/storage.rs b/lib/config/storage.rs
new file mode 100644
index 0000000..7c668e6
--- /dev/null
+++ b/lib/config/storage.rs
@@ -0,0 +1,123 @@
+use crate::AppConfig;
+
+impl AppConfig {
+    pub fn storage_backend(&self) -> anyhow::Result<String> {
+        let backend = self
+            .env
+            .get("APP_STORAGE_BACKEND")
+            .or_else(|| self.env.get("STORAGE_BACKEND"))
+            .map(|value| value.trim().to_ascii_lowercase())
+            .filter(|value| !value.is_empty())
+            .unwrap_or_else(|| "s3".to_string());
+
+        Ok(backend)
+    }
+
+    pub fn storage_path(&self) -> String {
+        self.env
+            .get("STORAGE_PATH")
+            .cloned()
+            .unwrap_or_else(|| "/data".to_string())
+    }
+
+    pub fn storage_public_url(&self) -> String {
+        self.env
+            .get("APP_STORAGE_PUBLIC_URL")
+            .or_else(|| self.env.get("STORAGE_PUBLIC_URL"))
+            .cloned()
+            .unwrap_or_else(|| "/files".to_string())
+    }
+
+    pub fn storage_public_url_base(&self) -> Option<String> {
+        self.env
+            .get("APP_STORAGE_PUBLIC_URL")
+            .or_else(|| self.env.get("STORAGE_PUBLIC_URL"))
+            .map(|value| value.trim().trim_end_matches('/').to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    pub fn storage_s3_bucket(&self) -> anyhow::Result<String> {
+        self.env
+            .get("APP_STORAGE_S3_BUCKET")
+            .or_else(|| self.env.get("AWS_S3_BUCKET"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+            .ok_or_else(|| anyhow::anyhow!("APP_STORAGE_S3_BUCKET is required"))
+    }
+
+    pub fn storage_s3_region(&self) -> String {
+        self.env
+            .get("APP_STORAGE_S3_REGION")
+            .or_else(|| self.env.get("AWS_REGION"))
+            .or_else(|| self.env.get("AWS_DEFAULT_REGION"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+            .unwrap_or_else(|| "us-east-1".to_string())
+    }
+
+    pub fn storage_s3_endpoint_url(&self) -> Option<String> {
+        self.env
+            .get("APP_STORAGE_S3_ENDPOINT_URL")
+            .or_else(|| self.env.get("AWS_ENDPOINT_URL_S3"))
+            .or_else(|| self.env.get("AWS_ENDPOINT_URL"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    pub fn storage_s3_access_key_id(&self) -> Option<String> {
+        self.env
+            .get("APP_STORAGE_S3_ACCESS_KEY_ID")
+            .or_else(|| self.env.get("AWS_ACCESS_KEY_ID"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    pub fn storage_s3_secret_access_key(&self) -> Option<String> {
+        self.env
+            .get("APP_STORAGE_S3_SECRET_ACCESS_KEY")
+            .or_else(|| self.env.get("AWS_SECRET_ACCESS_KEY"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    pub fn storage_s3_session_token(&self) -> Option<String> {
+        self.env
+            .get("APP_STORAGE_S3_SESSION_TOKEN")
+            .or_else(|| self.env.get("AWS_SESSION_TOKEN"))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    pub fn storage_s3_force_path_style(&self) -> anyhow::Result<bool> {
+        self.parse_env("APP_STORAGE_S3_FORCE_PATH_STYLE", false)
+    }
+
+    pub fn storage_presigned_url_ttl(
+        &self,
+    ) -> anyhow::Result<std::time::Duration> {
+        self.parse_duration_secs("APP_STORAGE_PRESIGNED_URL_TTL_SECONDS", 900)
+    }
+
+    pub fn storage_max_file_size(&self) -> usize {
+        self.env
+            .get("APP_STORAGE_MAX_FILE_SIZE")
+            .or_else(|| self.env.get("STORAGE_MAX_FILE_SIZE"))
+            .and_then(|s| s.parse::<usize>().ok())
+            .unwrap_or(10 * 1024 * 1024) // 10MB default
+    }
+
+    pub fn vapid_public_key(&self) -> Option<String> {
+        self.env.get("VAPID_PUBLIC_KEY").cloned()
+    }
+
+    pub fn vapid_private_key(&self) -> Option<String> {
+        self.env.get("VAPID_PRIVATE_KEY").cloned()
+    }
+
+    pub fn vapid_sender_email(&self) -> String {
+        self.env
+            .get("VAPID_SENDER_EMAIL")
+            .cloned()
+            .unwrap_or_else(|| "mailto:admin@example.com".to_string())
+    }
+}
diff --git a/lib/db/Cargo.toml b/lib/db/Cargo.toml
new file mode 100644
index 0000000..7529fbd
--- /dev/null
+++ b/lib/db/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "db"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "db"
+[dependencies]
+config = { workspace = true }
+sea-orm = { workspace = true }
+anyhow = { workspace = true }
+sqlx = { workspace = true, features = ["postgres","runtime-tokio"]}
+sqlparser = { workspace = true, features = [] }
+[lints]
+workspace = true
diff --git a/lib/db/database.rs b/lib/db/database.rs
new file mode 100644
index 0000000..7c25bd7
--- /dev/null
+++ b/lib/db/database.rs
@@ -0,0 +1,232 @@
+use std::{str::FromStr, time::Duration};
+
+use config::AppConfig;
+use sqlx::{
+    AssertSqlSafe, ConnectOptions, FromRow, PgPool,
+    postgres::{
+        PgArguments, PgConnectOptions, PgPoolOptions, PgQueryResult, PgRow,
+    },
+};
+
+use crate::{
+    route::{SqlRoute, route_sql},
+    transaction::AppTransaction,
+};
+
+#[derive(Clone)]
+pub struct AppDatabase {
+    db_write: PgPool,
+    db_read: Option<PgPool>,
+}
+
+impl AppDatabase {
+    pub async fn init(cfg: &AppConfig) -> anyhow::Result<Self> {
+        let db_url = cfg.database_url()?;
+        let max_connections = cfg.database_max_connections()?;
+        let min_connections = cfg.database_min_connections()?;
+        let idle_timeout = cfg.database_idle_timeout()?;
+        let max_lifetime = cfg.database_max_lifetime()?;
+        let connection_timeout = cfg.database_connection_timeout()?;
+        let schema_search_path = cfg.database_schema_search_path()?;
+        let read_replica = cfg.database_read_replicas()?;
+
+        let write_options = build_pg_options(&db_url, &schema_search_path)?;
+
+        let db_write = build_pool(
+            write_options,
+            max_connections,
+            min_connections,
+            idle_timeout,
+            max_lifetime,
+            connection_timeout,
+        )
+        .await?;
+
+        sqlx::query(AssertSqlSafe("SELECT 1".to_owned()))
+            .execute(&db_write)
+            .await?;
+
+        let db_read = if let Some(replica_url) = read_replica {
+            let read_options =
+                build_pg_options(&replica_url, &schema_search_path)?;
+
+            let pool = build_pool(
+                read_options,
+                max_connections,
+                min_connections,
+                idle_timeout,
+                max_lifetime,
+                connection_timeout,
+            )
+            .await?;
+
+            sqlx::query(AssertSqlSafe("SELECT 1".to_owned()))
+                .execute(&pool)
+                .await?;
+
+            Some(pool)
+        } else {
+            None
+        };
+
+        Ok(Self { db_write, db_read })
+    }
+
+    pub fn writer(&self) -> &PgPool {
+        &self.db_write
+    }
+
+    pub fn reader(&self) -> &PgPool {
+        self.db_read.as_ref().unwrap_or(&self.db_write)
+    }
+
+    pub fn route_pool(&self, sql: &str) -> &PgPool {
+        match route_sql(sql) {
+            SqlRoute::Write => self.writer(),
+            SqlRoute::Read => self.reader(),
+        }
+    }
+
+    pub async fn begin(&self) -> Result<AppTransaction<'_>, sqlx::Error> {
+        let txn = self.db_write.begin().await?;
+        Ok(AppTransaction { inner: txn })
+    }
+
+    pub async fn begin_read_only(
+        &self,
+    ) -> Result<AppTransaction<'_>, sqlx::Error> {
+        let mut txn = self.reader().begin().await?;
+
+        sqlx::query(AssertSqlSafe("SET TRANSACTION READ ONLY".to_owned()))
+            .execute(&mut *txn)
+            .await?;
+
+        Ok(AppTransaction { inner: txn })
+    }
+
+    pub async fn execute(
+        &self,
+        sql: &str,
+    ) -> Result<PgQueryResult, sqlx::Error> {
+        self.execute_with_args(sql, PgArguments::default()).await
+    }
+
+    pub async fn execute_with_args(
+        &self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<PgQueryResult, sqlx::Error> {
+        let pool = self.route_pool(sql);
+
+        sqlx::query_with(AssertSqlSafe(sql.to_owned()), args)
+            .execute(pool)
+            .await
+    }
+
+    pub async fn fetch_one<T>(&self, sql: &str) -> Result<T, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        self.fetch_one_with_args(sql, PgArguments::default()).await
+    }
+
+    pub async fn fetch_one_with_args<T>(
+        &self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<T, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        let pool = self.route_pool(sql);
+
+        sqlx::query_as_with::<_, T, _>(AssertSqlSafe(sql.to_owned()), args)
+            .fetch_one(pool)
+            .await
+    }
+
+    pub async fn fetch_optional<T>(
+        &self,
+        sql: &str,
+    ) -> Result<Option<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        self.fetch_optional_with_args(sql, PgArguments::default())
+            .await
+    }
+
+    pub async fn fetch_optional_with_args<T>(
+        &self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<Option<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        let pool = self.route_pool(sql);
+
+        sqlx::query_as_with::<_, T, _>(AssertSqlSafe(sql.to_owned()), args)
+            .fetch_optional(pool)
+            .await
+    }
+
+    pub async fn fetch_all<T>(&self, sql: &str) -> Result<Vec<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        self.fetch_all_with_args(sql, PgArguments::default()).await
+    }
+
+    pub async fn fetch_all_with_args<T>(
+        &self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<Vec<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        let pool = self.route_pool(sql);
+
+        sqlx::query_as_with::<_, T, _>(AssertSqlSafe(sql.to_owned()), args)
+            .fetch_all(pool)
+            .await
+    }
+}
+
+fn build_pg_options(
+    db_url: &str,
+    schema_search_path: &str,
+) -> anyhow::Result<PgConnectOptions> {
+    let options = PgConnectOptions::from_str(db_url)?
+        .options([("search_path", schema_search_path)])
+        .disable_statement_logging();
+
+    Ok(options)
+}
+
+async fn build_pool(
+    options: PgConnectOptions,
+    max_connections: u32,
+    min_connections: u32,
+    idle_timeout_secs: u64,
+    max_lifetime_secs: u64,
+    connection_timeout_secs: u64,
+) -> Result<PgPool, sqlx::Error> {
+    let mut pool_options = PgPoolOptions::new()
+        .max_connections(max_connections)
+        .min_connections(min_connections)
+        .acquire_timeout(Duration::from_secs(connection_timeout_secs.max(1)));
+
+    if idle_timeout_secs > 0 {
+        pool_options =
+            pool_options.idle_timeout(Duration::from_secs(idle_timeout_secs));
+    }
+
+    if max_lifetime_secs > 0 {
+        pool_options =
+            pool_options.max_lifetime(Duration::from_secs(max_lifetime_secs));
+    }
+
+    pool_options.connect_with(options).await
+}
diff --git a/lib/db/lib.rs b/lib/db/lib.rs
new file mode 100644
index 0000000..bcb6f73
--- /dev/null
+++ b/lib/db/lib.rs
@@ -0,0 +1,7 @@
+pub mod database;
+pub mod route;
+pub mod transaction;
+
+pub use database::AppDatabase;
+pub use sqlx;
+pub use transaction::AppTransaction;
diff --git a/lib/db/route.rs b/lib/db/route.rs
new file mode 100644
index 0000000..3f020a6
--- /dev/null
+++ b/lib/db/route.rs
@@ -0,0 +1,88 @@
+use sqlparser::{
+    ast::{Query, SetExpr, Statement},
+    dialect::PostgreSqlDialect,
+    parser::Parser,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SqlRoute {
+    Read,
+    Write,
+}
+
+pub fn route_sql(sql: &str) -> SqlRoute {
+    let trimmed = sql.trim_start();
+
+    if starts_with_hint(trimmed, "write") {
+        return SqlRoute::Write;
+    }
+
+    if starts_with_hint(trimmed, "read") {
+        return SqlRoute::Read;
+    }
+
+    if is_read_query_by_ast(sql) {
+        SqlRoute::Read
+    } else {
+        SqlRoute::Write
+    }
+}
+
+fn starts_with_hint(sql: &str, hint: &str) -> bool {
+    let expected = format!("/*+ {hint} */");
+    sql.starts_with(&expected)
+}
+
+fn is_read_query_by_ast(sql: &str) -> bool {
+    let dialect = PostgreSqlDialect {};
+
+    let Ok(statements) = Parser::parse_sql(&dialect, sql) else {
+        return false;
+    };
+
+    if statements.is_empty() {
+        return false;
+    }
+
+    statements.iter().all(is_read_statement)
+}
+
+fn is_read_statement(statement: &Statement) -> bool {
+    match statement {
+        Statement::Query(query) => is_read_query_ast(query),
+        Statement::ShowVariable { .. }
+        | Statement::ShowVariables { .. }
+        | Statement::ShowCreate { .. }
+        | Statement::ShowColumns { .. }
+        | Statement::ShowTables { .. } => true,
+        _ => false,
+    }
+}
+
+fn is_read_query_ast(query: &Query) -> bool {
+    if !query.locks.is_empty() {
+        return false;
+    }
+
+    match query.body.as_ref() {
+        SetExpr::Select(_) => true,
+        SetExpr::Query(inner) => is_read_query_ast(inner),
+        SetExpr::SetOperation { left, right, .. } => {
+            is_read_set_expr(left) && is_read_set_expr(right)
+        }
+        SetExpr::Values(_) => true,
+        _ => false,
+    }
+}
+
+fn is_read_set_expr(expr: &SetExpr) -> bool {
+    match expr {
+        SetExpr::Select(_) => true,
+        SetExpr::Query(query) => is_read_query_ast(query),
+        SetExpr::SetOperation { left, right, .. } => {
+            is_read_set_expr(left) && is_read_set_expr(right)
+        }
+        SetExpr::Values(_) => true,
+        _ => false,
+    }
+}
diff --git a/lib/db/transaction.rs b/lib/db/transaction.rs
new file mode 100644
index 0000000..1f3c5a5
--- /dev/null
+++ b/lib/db/transaction.rs
@@ -0,0 +1,98 @@
+use sqlx::{
+    AssertSqlSafe, FromRow, Postgres, Transaction,
+    postgres::{PgArguments, PgQueryResult, PgRow},
+};
+
+pub struct AppTransaction<'a> {
+    pub(crate) inner: Transaction<'a, Postgres>,
+}
+
+impl<'a> AppTransaction<'a> {
+    pub fn inner_mut(&mut self) -> &mut Transaction<'a, Postgres> {
+        &mut self.inner
+    }
+    pub async fn commit(self) -> Result<(), sqlx::Error> {
+        self.inner.commit().await
+    }
+    pub async fn rollback(self) -> Result<(), sqlx::Error> {
+        self.inner.rollback().await
+    }
+    pub async fn execute(
+        &mut self,
+        sql: &str,
+    ) -> Result<PgQueryResult, sqlx::Error> {
+        self.execute_with_args(sql, PgArguments::default()).await
+    }
+    pub async fn execute_with_args(
+        &mut self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<PgQueryResult, sqlx::Error> {
+        sqlx::query_with(AssertSqlSafe(sql.to_owned()), args)
+            .execute(&mut *self.inner)
+            .await
+    }
+    pub async fn fetch_one<T>(&mut self, sql: &str) -> Result<T, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        self.fetch_one_with_args(sql, PgArguments::default()).await
+    }
+    pub async fn fetch_one_with_args<T>(
+        &mut self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<T, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        sqlx::query_as_with::<_, T, _>(AssertSqlSafe(sql.to_owned()), args)
+            .fetch_one(&mut *self.inner)
+            .await
+    }
+    pub async fn fetch_optional<T>(
+        &mut self,
+        sql: &str,
+    ) -> Result<Option<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        self.fetch_optional_with_args(sql, PgArguments::default())
+            .await
+    }
+
+    pub async fn fetch_optional_with_args<T>(
+        &mut self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<Option<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        sqlx::query_as_with::<_, T, _>(AssertSqlSafe(sql.to_owned()), args)
+            .fetch_optional(&mut *self.inner)
+            .await
+    }
+    pub async fn fetch_all<T>(
+        &mut self,
+        sql: &str,
+    ) -> Result<Vec<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        self.fetch_all_with_args(sql, PgArguments::default()).await
+    }
+
+    pub async fn fetch_all_with_args<T>(
+        &mut self,
+        sql: &str,
+        args: PgArguments,
+    ) -> Result<Vec<T>, sqlx::Error>
+    where
+        for<'r> T: FromRow<'r, PgRow> + Send + Unpin,
+    {
+        sqlx::query_as_with::<_, T, _>(AssertSqlSafe(sql.to_owned()), args)
+            .fetch_all(&mut *self.inner)
+            .await
+    }
+}
diff --git a/lib/email/Cargo.toml b/lib/email/Cargo.toml
new file mode 100644
index 0000000..6a68416
--- /dev/null
+++ b/lib/email/Cargo.toml
@@ -0,0 +1,31 @@
+[package]
+name = "email"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "email"
+
+[dependencies]
+anyhow = { workspace = true }
+async-trait = { workspace = true }
+config = { workspace = true }
+lettre = { workspace = true }
+queue = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+tokio = { workspace = true, features = ["rt", "time"] }
+tracing = { workspace = true }
+
+[lints]
+workspace = true
diff --git a/lib/email/app.rs b/lib/email/app.rs
new file mode 100644
index 0000000..cec57db
--- /dev/null
+++ b/lib/email/app.rs
@@ -0,0 +1,39 @@
+use config::AppConfig;
+use queue::NatsProducer;
+
+use crate::EmailMessage;
+
+#[derive(Clone)]
+pub struct AppEmail {
+    producer: NatsProducer,
+    topic: String,
+}
+
+impl AppEmail {
+    pub async fn init(config: &AppConfig) -> anyhow::Result<Self> {
+        Ok(Self {
+            producer: NatsProducer::new(config).await?,
+            topic: config.email_topic(),
+        })
+    }
+
+    pub fn with_topic(
+        producer: NatsProducer,
+        topic: impl Into<String>,
+    ) -> Self {
+        Self {
+            producer,
+            topic: topic.into(),
+        }
+    }
+
+    pub async fn send(&self, message: EmailMessage) -> anyhow::Result<()> {
+        self.producer
+            .send(&self.topic, &message.to, &message, None)
+            .await
+    }
+
+    pub fn topic(&self) -> &str {
+        &self.topic
+    }
+}
diff --git a/lib/email/lib.rs b/lib/email/lib.rs
new file mode 100644
index 0000000..dae02d9
--- /dev/null
+++ b/lib/email/lib.rs
@@ -0,0 +1,9 @@
+mod app;
+mod message;
+mod smtp;
+mod worker;
+
+pub use app::AppEmail;
+pub use message::EmailMessage;
+pub use smtp::SmtpEmailSender;
+pub use worker::EmailWorker;
diff --git a/lib/email/message.rs b/lib/email/message.rs
new file mode 100644
index 0000000..00cb48f
--- /dev/null
+++ b/lib/email/message.rs
@@ -0,0 +1,8 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct EmailMessage {
+    pub to: String,
+    pub subject: String,
+    pub body: String,
+}
diff --git a/lib/email/smtp.rs b/lib/email/smtp.rs
new file mode 100644
index 0000000..5160ba5
--- /dev/null
+++ b/lib/email/smtp.rs
@@ -0,0 +1,135 @@
+use std::time::Duration;
+
+use config::AppConfig;
+use lettre::{
+    Message, Transport,
+    message::{Mailbox, header::ContentType},
+    transport::smtp::{PoolConfig, SmtpTransport, authentication::Credentials},
+};
+use tracing::warn;
+
+use crate::EmailMessage;
+
+#[derive(Clone)]
+pub struct SmtpEmailSender {
+    mailer: SmtpTransport,
+    from: Mailbox,
+    retry_attempts: u32,
+    retry_base_delay: Duration,
+}
+
+impl SmtpEmailSender {
+    pub fn new(config: &AppConfig) -> anyhow::Result<Self> {
+        let smtp_host = config.smtp_host()?;
+        let smtp_port = config.smtp_port()?;
+        let smtp_username = config.smtp_username()?;
+        let smtp_password = config.smtp_password()?;
+        let smtp_from = config.smtp_from()?;
+        let smtp_tls = config.smtp_tls()?;
+        let smtp_timeout = config.smtp_timeout()?;
+
+        let builder = if smtp_tls {
+            if smtp_port == 465 {
+                SmtpTransport::relay(&smtp_host)?
+            } else {
+                SmtpTransport::starttls_relay(&smtp_host)?
+            }
+        } else {
+            SmtpTransport::builder_dangerous(&smtp_host)
+        };
+
+        let mailer = builder
+            .credentials(Credentials::new(smtp_username, smtp_password))
+            .port(smtp_port)
+            .timeout(Some(Duration::from_secs(smtp_timeout)))
+            .pool_config(PoolConfig::new().min_idle(0).max_size(10))
+            .build();
+
+        Ok(Self {
+            mailer,
+            from: smtp_from.parse()?,
+            retry_attempts: config.email_send_retry_attempts(),
+            retry_base_delay: Duration::from_secs(
+                config.email_send_retry_base_delay_secs(),
+            ),
+        })
+    }
+
+    pub async fn send(&self, message: EmailMessage) -> anyhow::Result<()> {
+        let recipient: Mailbox = message.to.parse()?;
+        let email = Message::builder()
+            .from(self.from.clone())
+            .to(recipient)
+            .subject(message.subject)
+            .header(ContentType::TEXT_PLAIN)
+            .body(message.body)?;
+
+        let attempts = self.retry_attempts.max(1);
+        let mut last_error = None;
+
+        for attempt in 0..attempts {
+            let mailer = self.mailer.clone();
+            let email = email.clone();
+            let result =
+                tokio::task::spawn_blocking(move || mailer.send(&email)).await;
+
+            match result {
+                Ok(Ok(_)) => return Ok(()),
+                Ok(Err(error)) => {
+                    last_error = Some(anyhow::anyhow!(error));
+                    warn!(attempt = attempt + 1, "email send attempt failed");
+                }
+                Err(error) => {
+                    return Err(anyhow::anyhow!(
+                        "email send task failed: {error}"
+                    ));
+                }
+            }
+
+            if attempt + 1 < attempts {
+                let multiplier =
+                    1u64.checked_shl(attempt).unwrap_or(u64::MAX).max(1);
+                tokio::time::sleep(
+                    self.retry_base_delay.saturating_mul(multiplier as u32),
+                )
+                .await;
+            }
+        }
+
+        Err(last_error.unwrap_or_else(|| anyhow::anyhow!("email send failed")))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::HashMap;
+
+    use config::AppConfig;
+
+    use super::SmtpEmailSender;
+
+    #[test]
+    fn smtp_config_accepts_credentials_with_url_special_characters() {
+        let config = AppConfig {
+            env: HashMap::from([
+                ("APP_SMTP_HOST".to_string(), "smtp.example.com".to_string()),
+                ("APP_SMTP_PORT".to_string(), "587".to_string()),
+                (
+                    "APP_SMTP_USERNAME".to_string(),
+                    "user@example.com".to_string(),
+                ),
+                (
+                    "APP_SMTP_PASSWORD".to_string(),
+                    "p@ss:word/with?chars".to_string(),
+                ),
+                (
+                    "APP_SMTP_FROM".to_string(),
+                    "Gitdata <noreply@example.com>".to_string(),
+                ),
+                ("APP_SMTP_TLS".to_string(), "true".to_string()),
+            ]),
+        };
+
+        assert!(SmtpEmailSender::new(&config).is_ok());
+    }
+}
diff --git a/lib/email/worker.rs b/lib/email/worker.rs
new file mode 100644
index 0000000..f48693f
--- /dev/null
+++ b/lib/email/worker.rs
@@ -0,0 +1,46 @@
+use config::AppConfig;
+use queue::{AckAction, MessageHandler, NatsConsumer};
+use tracing::error;
+
+use crate::{EmailMessage, SmtpEmailSender};
+
+pub struct EmailWorker {
+    sender: SmtpEmailSender,
+}
+
+impl EmailWorker {
+    pub fn new(sender: SmtpEmailSender) -> Self {
+        Self { sender }
+    }
+
+    pub async fn start(config: &AppConfig) -> anyhow::Result<()> {
+        let worker = Self::new(SmtpEmailSender::new(config)?);
+        let consumer =
+            NatsConsumer::new(config, &config.email_consumer_group_id())
+                .await?;
+        let topic = config.email_topic();
+        consumer.start_consuming(&[topic.as_str()], worker).await?;
+        std::future::pending().await
+    }
+}
+
+#[async_trait::async_trait]
+impl MessageHandler for EmailWorker {
+    async fn handle(&self, topic: &str, payload: &[u8]) -> AckAction {
+        let message = match serde_json::from_slice::<EmailMessage>(payload) {
+            Ok(message) => message,
+            Err(error) => {
+                error!(topic, error = %error, "invalid email message payload");
+                return AckAction::Ack;
+            }
+        };
+
+        match self.sender.send(message).await {
+            Ok(()) => AckAction::Ack,
+            Err(error) => {
+                error!(topic, error = %error, "email message send failed");
+                AckAction::Nack
+            }
+        }
+    }
+}
diff --git a/lib/git/Cargo.toml b/lib/git/Cargo.toml
new file mode 100644
index 0000000..4ce22b3
--- /dev/null
+++ b/lib/git/Cargo.toml
@@ -0,0 +1,68 @@
+[package]
+name = "git"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "git"
+
+[dependencies]
+thiserror = { workspace = true }
+cache = { workspace = true }
+db = { workspace = true }
+storage = { workspace = true }
+config = { workspace = true }
+juniper = { workspace = true, features = [] }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "sync", "process", "io-util"] }
+anyhow = { workspace = true }
+duct = { workspace = true }
+gix = { workspace = true }
+gix-archive = { workspace = true }
+gix-worktree-stream = { workspace = true }
+model = { workspace = true }
+sqlx = { workspace = true, features = ["derive", "postgres", "runtime-tokio", "uuid", "chrono"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+tonic = { workspace = true }
+prost = { workspace = true }
+dashmap = { workspace = true }
+tracing = { workspace = true }
+tokio-stream = { workspace = true }
+actix-web = { workspace = true, features = [] }
+russh = { workspace = true, features = ["async-trait","rsa","legacy-ed25519-pkcs8-parser","serde"] }
+hmac = { workspace = true }
+hex = { workspace = true }
+reqwest = { workspace = true }
+async-stream = { workspace = true }
+async-trait = { workspace = true }
+tokio-util = { workspace = true }
+argon2 = { workspace = true }
+password-hash = { workspace = true }
+base64 = { workspace = true }
+sha2 = { workspace = true }
+uuid = { workspace = true, features = ["v4", "v7"] }
+chrono = { workspace = true }
+futures-util = { workspace = true }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp"] }
+deadpool-redis = { workspace = true }
+serde_yaml = { workspace = true }
+num_cpus = { workspace = true }
+miette = { workspace = true }
+parsefile = { workspace = true }
+tonic-prost = { workspace = true }
+
+[build-dependencies]
+tonic-build = { workspace = true }
+tonic-prost-build = "0.14.6"
+[lints]
+workspace = true
diff --git a/lib/git/bare.rs b/lib/git/bare.rs
new file mode 100644
index 0000000..98f223c
--- /dev/null
+++ b/lib/git/bare.rs
@@ -0,0 +1,134 @@
+use std::path::PathBuf;
+
+use crate::errors::GitResult;
+
+#[derive(Clone)]
+pub struct GitBare {
+    pub bare_dir: PathBuf,
+}
+
+#[derive(Debug, Clone)]
+pub struct LastCommitInfo {
+    pub message: String,
+    pub time: String,
+    pub author_name: String,
+    pub author_email: String,
+}
+
+impl GitBare {
+    pub fn gix_repo(&self) -> crate::errors::GitResult<gix::Repository> {
+        gix::open(&self.bare_dir).map_err(|e| {
+            crate::errors::GitError::Internal(format!(
+                "failed to open gix repository: {e}"
+            ))
+        })
+    }
+    pub fn set_default_branch(&self, branch_name: &str) -> GitResult<()> {
+        let output = self.git_command_trusted(vec![
+            "symbolic-ref".to_string(),
+            "HEAD".to_string(),
+            format!("refs/heads/{}", branch_name),
+        ])?;
+        if !output.success {
+            return Err(crate::errors::GitError::CommandFailed {
+                status_code: output.status_code,
+                stderr: output.stderr_lossy(),
+            });
+        }
+        Ok(())
+    }
+    pub fn last_commits_for_paths(&self, paths: &[String]) -> GitResult<Vec<Option<LastCommitInfo>>> {
+        use gix::traverse::commit::simple::CommitTimeOrder;
+
+        if paths.is_empty() {
+            return Ok(vec![]);
+        }
+
+        let repo = self.gix_repo()?;
+        let head_id = repo.head_id()
+            .map_err(|e| crate::errors::GitError::Internal(format!("no HEAD: {e}")))?;
+
+        let walk = repo.rev_walk(vec![head_id.detach()])
+            .sorting(gix::revision::walk::Sorting::ByCommitTime(CommitTimeOrder::NewestFirst))
+            .first_parent_only()
+            .all()
+            .map_err(|e| crate::errors::GitError::Internal(format!("rev_walk: {e}")))?;
+
+        let mut result: Vec<Option<LastCommitInfo>> = vec![None; paths.len()];
+        let mut remaining: std::collections::HashSet<usize> = (0..paths.len()).collect();
+
+        for walk_item in walk {
+            if remaining.is_empty() {
+                break;
+            }
+            let info = match walk_item {
+                Ok(i) => i,
+                Err(_) => continue,
+            };
+            let oid = info.id().detach();
+            let commit = match repo.find_commit(oid) {
+                Ok(c) => c,
+                Err(_) => continue,
+            };
+            let decoded = match commit.decode() {
+                Ok(d) => d,
+                Err(_) => continue,
+            };
+
+            let current_tree = match repo.find_tree(decoded.tree()) {
+                Ok(t) => t,
+                Err(_) => continue,
+            };
+
+            let parent_tree = decoded.parents().next().and_then(|pid| {
+                let hex = pid.to_hex().to_string();
+                let gid = gix::hash::ObjectId::from_hex(hex.as_bytes()).ok()?;
+                let pc = repo.find_commit(gid).ok()?;
+                let p_decoded = pc.decode().ok()?;
+                repo.find_tree(p_decoded.tree()).ok()
+            });
+
+            let mut diff_opts = gix::diff::Options::default();
+            diff_opts.track_path();
+            let changes = match repo.diff_tree_to_tree(
+                parent_tree.as_ref(),
+                Some(&current_tree),
+                Some(diff_opts),
+            ) {
+                Ok(d) => d,
+                Err(_) => continue,
+            };
+
+            let changed: std::collections::HashSet<String> = changes.iter()
+                .map(|c| c.location().to_string())
+                .collect();
+
+            let is_root = parent_tree.is_none();
+            let author_sig = match decoded.author() {
+                Ok(s) => s,
+                Err(_) => continue,
+            };
+            let time = author_sig.time().unwrap_or(gix::date::Time { seconds: 0, offset: 0 });
+            let msg = commit.message_raw()
+                .map(|r| r.to_string().trim_end_matches('\n').to_string())
+                .unwrap_or_default();
+            let summary = msg.lines().next().unwrap_or("").to_string();
+
+            let matched: Vec<usize> = remaining.iter().copied().filter(|&idx| {
+                is_root || changed.contains(&paths[idx])
+            }).collect();
+
+            for idx in matched {
+                result[idx] = Some(LastCommitInfo {
+                    message: summary.clone(),
+                    time: format!("{}", time.seconds),
+                    author_name: author_sig.name.to_string(),
+                    author_email: author_sig.email.to_string(),
+                });
+                remaining.remove(&idx);
+            }
+        }
+
+        Ok(result)
+    }
+}
diff --git a/lib/git/build.rs b/lib/git/build.rs
new file mode 100644
index 0000000..9c79321
--- /dev/null
+++ b/lib/git/build.rs
@@ -0,0 +1,25 @@
+fn main() {
+    let proto_dir = "proto";
+
+    let protos = [
+        format!("{proto_dir}/common.proto"),
+        format!("{proto_dir}/archive.proto"),
+        format!("{proto_dir}/blame.proto"),
+        format!("{proto_dir}/blob.proto"),
+        format!("{proto_dir}/branch.proto"),
+        format!("{proto_dir}/commit.proto"),
+        format!("{proto_dir}/diff.proto"),
+        format!("{proto_dir}/fork.proto"),
+        format!("{proto_dir}/init.proto"),
+        format!("{proto_dir}/merge.proto"),
+        format!("{proto_dir}/tag.proto"),
+        format!("{proto_dir}/tree.proto"),
+    ];
+
+    tonic_prost_build::configure()
+        .type_attribute(".", "#[derive(serde::Serialize, serde::Deserialize)]")
+        .type_attribute("ObjectId", "#[serde(transparent)]")
+        .field_attribute("ObjectId.value", "#[serde(rename = \"0\")]")
+        .compile_protos(&protos, &[proto_dir.to_string()])
+        .unwrap_or_else(|e| panic!("Failed to compile protos: {e}"));
+}
diff --git a/lib/git/cmd/archive/mod.rs b/lib/git/cmd/archive/mod.rs
new file mode 100644
index 0000000..d6e5ba8
--- /dev/null
+++ b/lib/git/cmd/archive/mod.rs
@@ -0,0 +1,18 @@
+use serde::{Deserialize, Serialize};
+
+use crate::cmd::oid::ObjectId;
+
+pub mod tar;
+pub mod zip;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ArchiveOptions {
+    pub tree: ObjectId,
+    pub prefix: Option<String>,
+    pub pathspec: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ArchiveResult {
+    pub bytes: Vec<u8>,
+}
diff --git a/lib/git/cmd/archive/tar.rs b/lib/git/cmd/archive/tar.rs
new file mode 100644
index 0000000..8ee884c
--- /dev/null
+++ b/lib/git/cmd/archive/tar.rs
@@ -0,0 +1,53 @@
+use gix::error::ResultExt;
+
+use crate::{
+    bare::GitBare,
+    cmd::archive::{ArchiveOptions, ArchiveResult},
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn archive_tar(
+        &self,
+        options: ArchiveOptions,
+    ) -> GitResult<ArchiveResult> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&options.tree).try_into()?;
+        let tree_id = {
+            let gix_id = gix_id;
+            if let Ok(tree) = repo.find_tree(gix_id) {
+                tree.id().detach()
+            } else {
+                let commit = repo
+                    .find_commit(gix_id)
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+                commit
+                    .tree_id()
+                    .map_err(|e| GitError::Gix(e.to_string()))?
+                    .detach()
+            }
+        };
+
+        let (mut stream, _index) = repo
+            .worktree_stream(tree_id)
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut buf: Vec<u8> = Vec::new();
+
+        let archive_opts = gix_archive::Options {
+            format: gix_archive::Format::Tar,
+            tree_prefix: options.prefix.map(|p| gix::bstr::BString::from(p)),
+            ..Default::default()
+        };
+
+        gix_archive::write_stream_seek(
+            &mut stream,
+            |stream| stream.next_entry().or_erased(),
+            std::io::Cursor::new(&mut buf),
+            archive_opts,
+        )
+        .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        Ok(ArchiveResult { bytes: buf })
+    }
+}
diff --git a/lib/git/cmd/archive/zip.rs b/lib/git/cmd/archive/zip.rs
new file mode 100644
index 0000000..95f0726
--- /dev/null
+++ b/lib/git/cmd/archive/zip.rs
@@ -0,0 +1,55 @@
+use gix::error::ResultExt;
+
+use crate::{
+    bare::GitBare,
+    cmd::archive::{ArchiveOptions, ArchiveResult},
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn archive_zip(
+        &self,
+        options: ArchiveOptions,
+    ) -> GitResult<ArchiveResult> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&options.tree).try_into()?;
+        let tree_id = {
+            let gix_id = gix_id;
+            if let Ok(tree) = repo.find_tree(gix_id) {
+                tree.id().detach()
+            } else {
+                let commit = repo
+                    .find_commit(gix_id)
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+                commit
+                    .tree_id()
+                    .map_err(|e| GitError::Gix(e.to_string()))?
+                    .detach()
+            }
+        };
+
+        let (mut stream, _index) = repo
+            .worktree_stream(tree_id)
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut buf: Vec<u8> = Vec::new();
+
+        let archive_opts = gix_archive::Options {
+            format: gix_archive::Format::Zip {
+                compression_level: None,
+            },
+            tree_prefix: options.prefix.map(|p| gix::bstr::BString::from(p)),
+            ..Default::default()
+        };
+
+        gix_archive::write_stream_seek(
+            &mut stream,
+            |stream| stream.next_entry().or_erased(),
+            std::io::Cursor::new(&mut buf),
+            archive_opts,
+        )
+        .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        Ok(ArchiveResult { bytes: buf })
+    }
+}
diff --git a/lib/git/cmd/blame/blame_file.rs b/lib/git/cmd/blame/blame_file.rs
new file mode 100644
index 0000000..5986b0f
--- /dev/null
+++ b/lib/git/cmd/blame/blame_file.rs
@@ -0,0 +1,96 @@
+use std::path::Path;
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        blame::{BlameOptions, CommitBlameHunk},
+        oid::ObjectId,
+    },
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn blame_file(
+        &self,
+        oid: ObjectId,
+        path: impl AsRef<Path>,
+        opts: Option<BlameOptions>,
+    ) -> GitResult<Vec<CommitBlameHunk>> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+
+        let blame_opts = opts.unwrap_or_default();
+        let ranges = if let (Some(min), Some(max)) =
+            (blame_opts.min_line, blame_opts.max_line)
+        {
+            gix::blame::BlameRanges::from_one_based_inclusive_range(
+                min as u32..=max as u32,
+            )?
+        } else if let Some(min) = blame_opts.min_line {
+            gix::blame::BlameRanges::from_one_based_inclusive_range(
+                min as u32..=min as u32,
+            )?
+        } else {
+            gix::blame::BlameRanges::default()
+        };
+
+        let rewrites = if blame_opts.track_copies_same_file
+            || blame_opts.track_copies_same_commit_moves
+        {
+            Some(gix::diff::Rewrites::default())
+        } else {
+            None
+        };
+
+        let gix_options = gix::repository::blame_file::Options {
+            diff_algorithm: None,
+            ranges,
+            since: None,
+            rewrites,
+        };
+
+        let outcome = repo.blame_file(
+            path.as_ref()
+                .as_os_str()
+                .to_string_lossy()
+                .as_bytes()
+                .as_ref(),
+            gix_id,
+            gix_options,
+        )?;
+
+        let mut hunks = Vec::new();
+
+        for entry in outcome.entries {
+            let range_in_blamed = entry.range_in_blamed_file();
+            let range_in_source = entry.range_in_source_file();
+
+            let commit_oid =
+                ObjectId::new(entry.commit_id.to_hex().to_string());
+            let final_start_line = range_in_blamed.start as u32 + 1;
+            let final_lines = range_in_blamed.len() as u32;
+            let orig_start_line = range_in_source.start as u32 + 1;
+            let orig_lines = range_in_source.len() as u32;
+
+            let is_boundary = repo
+                .find_commit(entry.commit_id)
+                .ok()
+                .is_some_and(|c| c.parent_ids().count() == 0);
+
+            let orig_path =
+                entry.source_file_name.as_ref().map(|p| p.to_string());
+
+            hunks.push(CommitBlameHunk {
+                commit_oid,
+                final_start_line,
+                final_lines,
+                orig_start_line,
+                orig_lines,
+                boundary: is_boundary,
+                orig_path,
+            });
+        }
+
+        Ok(hunks)
+    }
+}
diff --git a/lib/git/cmd/blame/blame_hunk.rs b/lib/git/cmd/blame/blame_hunk.rs
new file mode 100644
index 0000000..e048d1d
--- /dev/null
+++ b/lib/git/cmd/blame/blame_hunk.rs
@@ -0,0 +1,69 @@
+use std::path::Path;
+
+use crate::{
+    bare::GitBare,
+    cmd::{blame::CommitBlameHunk, oid::ObjectId},
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn blame_hunk(
+        &self,
+        oid: &ObjectId,
+        path: impl AsRef<Path>,
+        line_on: usize,
+    ) -> GitResult<CommitBlameHunk> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (oid).try_into()?;
+
+        let ranges = gix::blame::BlameRanges::from_one_based_inclusive_range(
+            line_on as u32..=line_on as u32,
+        )?;
+
+        let gix_options = gix::repository::blame_file::Options {
+            diff_algorithm: None,
+            ranges,
+            since: None,
+            rewrites: None,
+        };
+
+        let outcome = repo.blame_file(
+            path.as_ref()
+                .as_os_str()
+                .to_string_lossy()
+                .as_bytes()
+                .as_ref(),
+            gix_id,
+            gix_options,
+        )?;
+
+        let entry = outcome.entries.first().ok_or_else(|| {
+            GitError::ParseError(format!(
+                "no blame hunk found for line {} in {} at {}",
+                line_on,
+                path.as_ref().display(),
+                oid
+            ))
+        })?;
+
+        let range_in_blamed = entry.range_in_blamed_file();
+        let range_in_source = entry.range_in_source_file();
+
+        let commit_oid = ObjectId::new(entry.commit_id.to_hex().to_string());
+        let is_boundary = repo
+            .find_commit(entry.commit_id)
+            .ok()
+            .is_some_and(|c| c.parent_ids().count() == 0);
+        let orig_path = entry.source_file_name.as_ref().map(|p| p.to_string());
+
+        Ok(CommitBlameHunk {
+            commit_oid,
+            final_start_line: range_in_blamed.start as u32 + 1,
+            final_lines: range_in_blamed.len() as u32,
+            orig_start_line: range_in_source.start as u32 + 1,
+            orig_lines: range_in_source.len() as u32,
+            boundary: is_boundary,
+            orig_path,
+        })
+    }
+}
diff --git a/lib/git/cmd/blame/blame_line.rs b/lib/git/cmd/blame/blame_line.rs
new file mode 100644
index 0000000..4ef8811
--- /dev/null
+++ b/lib/git/cmd/blame/blame_line.rs
@@ -0,0 +1,84 @@
+use std::path::Path;
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        blame::{BlameOptions, CommitBlameLine},
+        oid::ObjectId,
+    },
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn blame_lines(
+        &self,
+        oid: ObjectId,
+        path: impl AsRef<Path>,
+        opts: Option<BlameOptions>,
+    ) -> GitResult<Vec<CommitBlameLine>> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+
+        let blame_opts = opts.unwrap_or_default();
+
+        let ranges = if let (Some(min), Some(max)) =
+            (blame_opts.min_line, blame_opts.max_line)
+        {
+            gix::blame::BlameRanges::from_one_based_inclusive_range(
+                min as u32..=max as u32,
+            )?
+        } else if let Some(min) = blame_opts.min_line {
+            gix::blame::BlameRanges::from_one_based_inclusive_range(
+                min as u32..=min as u32,
+            )?
+        } else {
+            gix::blame::BlameRanges::default()
+        };
+
+        let rewrites = if blame_opts.track_copies_same_file
+            || blame_opts.track_copies_same_commit_moves
+        {
+            Some(gix::diff::Rewrites::default())
+        } else {
+            None
+        };
+
+        let gix_options = gix::repository::blame_file::Options {
+            diff_algorithm: None,
+            ranges,
+            since: None,
+            rewrites,
+        };
+
+        let outcome = repo.blame_file(
+            path.as_ref()
+                .as_os_str()
+                .to_string_lossy()
+                .as_bytes()
+                .as_ref(),
+            gix_id,
+            gix_options,
+        )?;
+
+        let mut result = Vec::new();
+
+        for (entry, lines) in outcome.entries_with_lines() {
+            let commit_oid =
+                ObjectId::new(entry.commit_id.to_hex().to_string());
+            let orig_path =
+                entry.source_file_name.as_ref().map(|p| p.to_string());
+            let base_line = entry.range_in_blamed_file().start as u32 + 1;
+
+            for (i, line) in lines.iter().enumerate() {
+                result.push(CommitBlameLine {
+                    commit_oid: commit_oid.clone(),
+                    line_no: base_line + i as u32,
+                    content: line.to_string(),
+                    orig_path: orig_path.clone(),
+                });
+            }
+        }
+
+        Ok(result)
+    }
+}
diff --git a/lib/git/cmd/blame/mod.rs b/lib/git/cmd/blame/mod.rs
new file mode 100644
index 0000000..b2b5992
--- /dev/null
+++ b/lib/git/cmd/blame/mod.rs
@@ -0,0 +1,65 @@
+use serde::{Deserialize, Serialize};
+
+use crate::cmd::oid::ObjectId;
+
+pub mod blame_file;
+pub mod blame_hunk;
+pub mod blame_line;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitBlameHunk {
+    pub commit_oid: ObjectId,
+    pub final_start_line: u32,
+    pub final_lines: u32,
+    pub orig_start_line: u32,
+    pub orig_lines: u32,
+    pub boundary: bool,
+    pub orig_path: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitBlameLine {
+    pub commit_oid: ObjectId,
+    pub line_no: u32,
+    pub content: String,
+    pub orig_path: Option<String>,
+}
+
+#[derive(Debug, Clone, Default, Deserialize, Serialize)]
+pub struct BlameOptions {
+    pub min_line: Option<usize>,
+    pub max_line: Option<usize>,
+    pub track_copies_same_file: bool,
+    pub track_copies_same_commit_moves: bool,
+    pub ignore_whitespace: bool,
+}
+
+impl BlameOptions {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn min_line(mut self, line: usize) -> Self {
+        self.min_line = Some(line);
+        self
+    }
+
+    pub fn max_line(mut self, line: usize) -> Self {
+        self.max_line = Some(line);
+        self
+    }
+    pub fn track_copies_same_file(mut self) -> Self {
+        self.track_copies_same_file = true;
+        self
+    }
+
+    pub fn track_copies_same_commit_moves(mut self) -> Self {
+        self.track_copies_same_commit_moves = true;
+        self
+    }
+
+    pub fn ignore_whitespace(mut self) -> Self {
+        self.ignore_whitespace = true;
+        self
+    }
+}
diff --git a/lib/git/cmd/blob/blob_chunk.rs b/lib/git/cmd/blob/blob_chunk.rs
new file mode 100644
index 0000000..92c2c67
--- /dev/null
+++ b/lib/git/cmd/blob/blob_chunk.rs
@@ -0,0 +1,46 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobChunkParam {
+    pub path: String,
+    pub oid: ObjectId,
+    pub size: usize,
+    pub offset: usize,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobChunk {
+    pub param: BlobChunkParam,
+    pub chunk: Vec<u8>,
+}
+
+impl GitBare {
+    pub fn blob_chunk(&self, param: BlobChunkParam) -> GitResult<BlobChunk> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&param.oid).try_into()?;
+
+        let blob = repo.find_blob(gix_id).map_err(|_| {
+            GitError::ObjectNotFound(param.oid.as_str().to_string())
+        })?;
+
+        let blob_bytes = blob.data.clone();
+        let end = param.offset + param.size;
+        if end > blob_bytes.len() {
+            return Err(GitError::ParseError(format!(
+                "chunk offset+size ({}) exceeds blob length ({})",
+                end,
+                blob_bytes.len()
+            )));
+        }
+
+        let chunk = blob_bytes[param.offset..end].to_vec();
+
+        Ok(BlobChunk { param, chunk })
+    }
+}
diff --git a/lib/git/cmd/blob/blob_helper.rs b/lib/git/cmd/blob/blob_helper.rs
new file mode 100644
index 0000000..ab3cf3c
--- /dev/null
+++ b/lib/git/cmd/blob/blob_helper.rs
@@ -0,0 +1,27 @@
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn blob_is_binary(&self, id: ObjectId) -> GitResult<bool> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&id).try_into()?;
+
+        let blob = repo
+            .find_blob(gix_id)
+            .map_err(|_| GitError::ObjectNotFound(id.as_str().to_string()))?;
+
+        let check_len = std::cmp::min(8000, blob.data.len());
+        let is_binary = blob.data[..check_len].contains(&0);
+
+        Ok(is_binary)
+    }
+
+    pub fn blob_exists(&self, id: ObjectId) -> GitResult<bool> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&id).try_into()?;
+        Ok(repo.has_object(gix_id))
+    }
+}
diff --git a/lib/git/cmd/blob/blob_load.rs b/lib/git/cmd/blob/blob_load.rs
new file mode 100644
index 0000000..c899ff0
--- /dev/null
+++ b/lib/git/cmd/blob/blob_load.rs
@@ -0,0 +1,38 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobLoadParams {
+    pub id: ObjectId,
+    pub path: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobLoadResult {
+    pub params: BlobLoadParams,
+    pub blob: Vec<u8>,
+}
+
+impl GitBare {
+    pub fn blob_load(
+        &self,
+        params: &BlobLoadParams,
+    ) -> GitResult<BlobLoadResult> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&params.id).try_into()?;
+
+        let blob = repo.find_blob(gix_id).map_err(|_| {
+            GitError::ObjectNotFound(params.id.as_str().to_string())
+        })?;
+
+        Ok(BlobLoadResult {
+            params: params.clone(),
+            blob: blob.data.to_vec(),
+        })
+    }
+}
diff --git a/lib/git/cmd/blob/blob_size.rs b/lib/git/cmd/blob/blob_size.rs
new file mode 100644
index 0000000..829891d
--- /dev/null
+++ b/lib/git/cmd/blob/blob_size.rs
@@ -0,0 +1,26 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobSizeParams {
+    pub id: ObjectId,
+    pub path: String,
+}
+
+impl GitBare {
+    pub fn blob_size(&self, params: &BlobSizeParams) -> GitResult<u64> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&params.id).try_into()?;
+
+        let header = repo.find_header(gix_id).map_err(|_| {
+            GitError::ObjectNotFound(params.id.as_str().to_string())
+        })?;
+
+        Ok(header.size() as u64)
+    }
+}
diff --git a/lib/git/cmd/blob/blob_upload.rs b/lib/git/cmd/blob/blob_upload.rs
new file mode 100644
index 0000000..e2e72a9
--- /dev/null
+++ b/lib/git/cmd/blob/blob_upload.rs
@@ -0,0 +1,47 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{command::GitCommandParams, oid::ObjectId},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobUploadParams {
+    pub blob: Vec<u8>,
+    pub path: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BlobUploadResult {
+    pub id: ObjectId,
+}
+
+impl GitBare {
+    pub fn blob_upload(
+        &self,
+        params: BlobUploadParams,
+    ) -> GitResult<BlobUploadResult> {
+        let cmd_params = GitCommandParams::new(vec![
+            "hash-object".to_string(),
+            "-w".to_string(),
+            "--stdin".to_string(),
+        ])
+        .with_stdin(params.blob);
+
+        let output = self.git_command_with(cmd_params)?;
+
+        if !output.success {
+            return Err(GitError::CommandFailed {
+                status_code: output.status_code,
+                stderr: output.stderr_lossy(),
+            });
+        }
+
+        let stdout = output.stdout_lossy();
+        let oid_str = stdout.trim();
+        let oid = ObjectId::new(oid_str);
+
+        Ok(BlobUploadResult { id: oid })
+    }
+}
diff --git a/lib/git/cmd/blob/mod.rs b/lib/git/cmd/blob/mod.rs
new file mode 100644
index 0000000..813dc54
--- /dev/null
+++ b/lib/git/cmd/blob/mod.rs
@@ -0,0 +1,10 @@
+pub mod blob_chunk;
+pub mod blob_helper;
+pub mod blob_load;
+pub mod blob_size;
+pub mod blob_upload;
+
+pub use blob_chunk::{BlobChunk, BlobChunkParam};
+pub use blob_load::{BlobLoadParams, BlobLoadResult};
+pub use blob_size::BlobSizeParams;
+pub use blob_upload::{BlobUploadParams, BlobUploadResult};
diff --git a/lib/git/cmd/branch/branch_delete.rs b/lib/git/cmd/branch/branch_delete.rs
new file mode 100644
index 0000000..dc28e1d
--- /dev/null
+++ b/lib/git/cmd/branch/branch_delete.rs
@@ -0,0 +1,18 @@
+use crate::{bare::GitBare, errors::GitResult};
+
+pub struct BranchDeleteParams {
+    pub name: String,
+    pub force: bool,
+}
+
+impl GitBare {
+    pub fn branch_delete(&self, params: BranchDeleteParams) -> GitResult<()> {
+        let flag = if params.force { "-D" } else { "-d" };
+        self.git_command_trusted(vec![
+            "branch".to_string(),
+            flag.to_string(),
+            params.name,
+        ])?;
+        Ok(())
+    }
+}
diff --git a/lib/git/cmd/branch/branch_fork.rs b/lib/git/cmd/branch/branch_fork.rs
new file mode 100644
index 0000000..1502422
--- /dev/null
+++ b/lib/git/cmd/branch/branch_fork.rs
@@ -0,0 +1,20 @@
+use crate::{bare::GitBare, cmd::oid::ObjectId, errors::GitResult};
+
+pub struct BranchForkParams {
+    pub name: String,
+    pub oid: ObjectId,
+    pub force: bool,
+}
+
+impl GitBare {
+    pub fn branch_fork(&self, params: &BranchForkParams) -> GitResult<()> {
+        let mut args = vec!["branch".to_string()];
+        if params.force {
+            args.push("--force".to_string());
+        }
+        args.push(params.name.clone());
+        args.push(params.oid.to_string());
+        self.git_command_trusted(args)?;
+        Ok(())
+    }
+}
diff --git a/lib/git/cmd/branch/branch_head.rs b/lib/git/cmd/branch/branch_head.rs
new file mode 100644
index 0000000..78c42ea
--- /dev/null
+++ b/lib/git/cmd/branch/branch_head.rs
@@ -0,0 +1,36 @@
+use crate::{bare::GitBare, errors::GitResult};
+
+impl GitBare {
+    pub fn branch_head_name(&self) -> GitResult<String> {
+        let repo = self.gix_repo()?;
+        let head_name = repo.head_name()?;
+        match head_name {
+            Some(name) => Ok(name.shorten().to_string()),
+            None => {
+                Err(crate::errors::GitError::RefNotFound("HEAD".to_string()))
+            }
+        }
+    }
+
+    pub fn branch_ahead_behind(&self, branch_name: String) -> GitResult<bool> {
+        let upstream = self.branch_upstream_name(branch_name.clone())?;
+        let upstream_name = match upstream {
+            Some(name) => name,
+            None => return Ok(false),
+        };
+
+        let repo = self.gix_repo()?;
+        let branch_id = repo
+            .rev_parse_single(branch_name.as_str())
+            .map_err(|_| crate::errors::GitError::RefNotFound(branch_name))?;
+        let upstream_id = repo
+            .rev_parse_single(upstream_name.as_str())
+            .map_err(|_| crate::errors::GitError::RefNotFound(upstream_name))?;
+
+        let branch_commit = branch_id.detach();
+        let upstream_commit = upstream_id.detach();
+        let merge_base = repo.merge_base(branch_commit, upstream_commit).ok();
+
+        Ok(merge_base.is_some_and(|base| base.detach() != branch_commit))
+    }
+}
diff --git a/lib/git/cmd/branch/branch_list.rs b/lib/git/cmd/branch/branch_list.rs
new file mode 100644
index 0000000..8e0fd30
--- /dev/null
+++ b/lib/git/cmd/branch/branch_list.rs
@@ -0,0 +1,133 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BranchListItem {
+    pub name: String,
+    pub oid: ObjectId,
+    pub is_head: bool,
+    pub is_remote: bool,
+    pub is_current: bool,
+    pub upstream: Option<String>,
+}
+
+impl GitBare {
+    pub fn branch_list_all(&self) -> GitResult<Vec<BranchListItem>> {
+        let repo = self.gix_repo()?;
+        let head_name = repo.head_name()?.map(|n| n.shorten().to_string());
+
+        let mut items = Vec::new();
+        let platform = repo.references()?;
+        let local_iter = platform.local_branches()?;
+        for ref_result in local_iter {
+            let reference = ref_result?;
+            let name = reference.name().shorten().to_string();
+            let is_head = head_name.as_ref() == Some(&name);
+            let is_current = is_head;
+
+            let target = reference.target();
+            let target_id = target.try_id().ok_or_else(|| {
+                GitError::Internal(
+                    "local branch has no direct target".to_string(),
+                )
+            })?;
+            let oid = ObjectId::new(target_id.to_hex().to_string());
+            let upstream = reference
+                .remote_tracking_ref_name(gix::remote::Direction::Fetch)
+                .and_then(|r| r.ok())
+                .map(|n| n.shorten().to_string());
+
+            items.push(BranchListItem {
+                name,
+                oid,
+                is_head,
+                is_remote: false,
+                is_current,
+                upstream,
+            });
+        }
+        let remote_iter = platform.remote_branches()?;
+        for ref_result in remote_iter {
+            let reference = ref_result?;
+            let name = reference.name().shorten().to_string();
+            let is_head = head_name.as_ref() == Some(&name);
+            let is_current = is_head;
+
+            let target = reference.target();
+            let target_id = target.try_id().ok_or_else(|| {
+                GitError::Internal(
+                    "remote branch has no direct target".to_string(),
+                )
+            })?;
+            let oid = ObjectId::new(target_id.to_hex().to_string());
+
+            items.push(BranchListItem {
+                name,
+                oid,
+                is_head,
+                is_remote: true,
+                is_current,
+                upstream: None,
+            });
+        }
+
+        Ok(items)
+    }
+
+    pub fn branch_info(&self, branch: String) -> GitResult<BranchListItem> {
+        let repo = self.gix_repo()?;
+        let head_name = repo.head_name()?.map(|n| n.shorten().to_string());
+        let local_ref_str = format!("refs/heads/{branch}");
+        let local_ref = repo.try_find_reference(local_ref_str.as_str())?;
+        if let Some(reference) = local_ref {
+            let name = reference.name().shorten().to_string();
+            let is_head = head_name.as_ref() == Some(&name);
+            let target = reference.target();
+            let target_id = target.try_id().ok_or_else(|| {
+                GitError::Internal("branch has no direct target".to_string())
+            })?;
+            let oid = ObjectId::new(target_id.to_hex().to_string());
+
+            let upstream = reference
+                .remote_tracking_ref_name(gix::remote::Direction::Fetch)
+                .and_then(|r| r.ok())
+                .map(|n| n.shorten().to_string());
+
+            return Ok(BranchListItem {
+                name,
+                oid,
+                is_head,
+                is_remote: false,
+                is_current: is_head,
+                upstream,
+            });
+        }
+        let remote_ref_str = format!("refs/remotes/{branch}");
+        let remote_ref = repo.try_find_reference(remote_ref_str.as_str())?;
+        if let Some(reference) = remote_ref {
+            let name = reference.name().shorten().to_string();
+            let is_head = head_name.as_ref() == Some(&name);
+            let target = reference.target();
+            let target_id = target.try_id().ok_or_else(|| {
+                GitError::Internal("branch has no direct target".to_string())
+            })?;
+            let oid = ObjectId::new(target_id.to_hex().to_string());
+
+            return Ok(BranchListItem {
+                name,
+                oid,
+                is_head,
+                is_remote: true,
+                is_current: is_head,
+                upstream: None,
+            });
+        }
+
+        Err(GitError::RefNotFound(branch))
+    }
+}
diff --git a/lib/git/cmd/branch/branch_rename.rs b/lib/git/cmd/branch/branch_rename.rs
new file mode 100644
index 0000000..0e451d0
--- /dev/null
+++ b/lib/git/cmd/branch/branch_rename.rs
@@ -0,0 +1,20 @@
+use crate::{bare::GitBare, errors::GitResult};
+
+pub struct BranchReNameParams {
+    pub old_branch: String,
+    pub new_branch: String,
+    pub force: bool,
+}
+
+impl GitBare {
+    pub fn branch_rename(&self, params: BranchReNameParams) -> GitResult<()> {
+        let flag = if params.force { "-M" } else { "-m" };
+        self.git_command_trusted(vec![
+            "branch".to_string(),
+            flag.to_string(),
+            params.old_branch,
+            params.new_branch,
+        ])?;
+        Ok(())
+    }
+}
diff --git a/lib/git/cmd/branch/branch_summary.rs b/lib/git/cmd/branch/branch_summary.rs
new file mode 100644
index 0000000..71d5202
--- /dev/null
+++ b/lib/git/cmd/branch/branch_summary.rs
@@ -0,0 +1,26 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{bare::GitBare, errors::GitResult};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BranchSummary {
+    pub local_count: usize,
+    pub remote_count: usize,
+    pub all_count: usize,
+}
+
+impl GitBare {
+    pub fn branch_summary(&self) -> GitResult<BranchSummary> {
+        let repo = self.gix_repo()?;
+        let platform = repo.references()?;
+
+        let local_count = platform.local_branches()?.count();
+        let remote_count = platform.remote_branches()?.count();
+
+        Ok(BranchSummary {
+            local_count,
+            remote_count,
+            all_count: local_count + remote_count,
+        })
+    }
+}
diff --git a/lib/git/cmd/branch/branch_upstream.rs b/lib/git/cmd/branch/branch_upstream.rs
new file mode 100644
index 0000000..5b420ec
--- /dev/null
+++ b/lib/git/cmd/branch/branch_upstream.rs
@@ -0,0 +1,40 @@
+use crate::{
+    bare::GitBare, cmd::branch::branch_list::BranchListItem, errors::GitResult,
+};
+
+impl GitBare {
+    pub fn branch_upstream_name(
+        &self,
+        branch_name: String,
+    ) -> GitResult<Option<String>> {
+        let repo = self.gix_repo()?;
+        let ref_str = format!("refs/heads/{branch_name}");
+        let reference = repo.find_reference(ref_str.as_str())?;
+
+        let upstream = reference
+            .remote_tracking_ref_name(gix::remote::Direction::Fetch)
+            .and_then(|r| r.ok())
+            .map(|n| n.shorten().to_string());
+
+        Ok(upstream)
+    }
+
+    pub fn branch_upstream(
+        &self,
+        branch_name: String,
+    ) -> GitResult<Option<BranchListItem>> {
+        let upstream_name = self.branch_upstream_name(branch_name)?;
+        match upstream_name {
+            Some(name) => {
+                let info = self.branch_info(name)?;
+                Ok(Some(info))
+            }
+            None => Ok(None),
+        }
+    }
+
+    pub fn branch_has_upstream(&self, branch_name: String) -> GitResult<bool> {
+        let upstream = self.branch_upstream_name(branch_name)?;
+        Ok(upstream.is_some())
+    }
+}
diff --git a/lib/git/cmd/branch/mod.rs b/lib/git/cmd/branch/mod.rs
new file mode 100644
index 0000000..474c76c
--- /dev/null
+++ b/lib/git/cmd/branch/mod.rs
@@ -0,0 +1,13 @@
+pub mod branch_delete;
+pub mod branch_fork;
+pub mod branch_head;
+pub mod branch_list;
+pub mod branch_rename;
+pub mod branch_summary;
+pub mod branch_upstream;
+
+pub use branch_delete::BranchDeleteParams;
+pub use branch_fork::BranchForkParams;
+pub use branch_list::BranchListItem;
+pub use branch_rename::BranchReNameParams;
+pub use branch_summary::BranchSummary;
diff --git a/lib/git/cmd/command.rs b/lib/git/cmd/command.rs
new file mode 100644
index 0000000..4aaded7
--- /dev/null
+++ b/lib/git/cmd/command.rs
@@ -0,0 +1,420 @@
+use std::{
+    ffi::{OsStr, OsString},
+    path::{Component, Path, PathBuf},
+};
+
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    errors::{GitError, GitResult},
+};
+
+const DANGEROUS_SUBCOMMANDS: &[&str] = &[
+    "add",
+    "apply",
+    "archive",
+    "bisect",
+    "bundle",
+    "checkout",
+    "clean",
+    "clone",
+    "commit",
+    "config",
+    "fetch",
+    "gc",
+    "hook",
+    "init",
+    "maintenance",
+    "merge",
+    "mv",
+    "notes",
+    "pull",
+    "push",
+    "rebase",
+    "remote",
+    "repack",
+    "replace",
+    "reset",
+    "restore",
+    "rm",
+    "send-email",
+    "sparse-checkout",
+    "stash",
+    "submodule",
+    "switch",
+    "update-index",
+    "update-ref",
+    "worktree",
+];
+
+const DANGEROUS_OPTIONS: &[&str] = &[
+    "-C",
+    "-c",
+    "--exec-path",
+    "--git-dir",
+    "--html-path",
+    "--man-path",
+    "--namespace",
+    "--paginate",
+    "--super-prefix",
+    "--upload-pack",
+    "--work-tree",
+];
+
+const DANGEROUS_OPTION_PREFIXES: &[&str] = &[
+    "--exec-path=",
+    "--git-dir=",
+    "--namespace=",
+    "--super-prefix=",
+    "--upload-pack=",
+    "--work-tree=",
+];
+
+const DENIED_ENV_NAMES: &[&str] = &[
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_CONFIG",
+    "GIT_CONFIG_COUNT",
+    "GIT_CONFIG_GLOBAL",
+    "GIT_CONFIG_NOSYSTEM",
+    "GIT_CONFIG_SYSTEM",
+    "GIT_DIR",
+    "GIT_EXEC_PATH",
+    "GIT_EXTERNAL_DIFF",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_SSH",
+    "GIT_SSH_COMMAND",
+    "GIT_WORK_TREE",
+    "LD_LIBRARY_PATH",
+    "PATH",
+];
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GitCommandParams {
+    pub args: Vec<String>,
+    pub env: Vec<(String, String)>,
+    pub stdin: Option<Vec<u8>>,
+    pub check_status: bool,
+    pub bypass_subcommand_validation: bool,
+}
+
+impl GitCommandParams {
+    pub fn new(args: Vec<String>) -> Self {
+        Self {
+            args,
+            env: Vec::new(),
+            stdin: None,
+            check_status: true,
+            bypass_subcommand_validation: false,
+        }
+    }
+
+    pub fn unchecked(mut self) -> Self {
+        self.check_status = false;
+        self
+    }
+
+    pub fn trusted(mut self) -> Self {
+        self.bypass_subcommand_validation = true;
+        self
+    }
+
+    pub fn with_stdin(mut self, stdin: Vec<u8>) -> Self {
+        self.stdin = Some(stdin);
+        self
+    }
+
+    pub fn with_env(mut self, name: String, value: String) -> Self {
+        self.env.push((name, value));
+        self
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GitCommandOutput {
+    pub status_code: Option<i32>,
+    pub success: bool,
+    pub stdout: Vec<u8>,
+    pub stderr: Vec<u8>,
+}
+
+impl GitCommandOutput {
+    pub fn stdout_lossy(&self) -> String {
+        String::from_utf8_lossy(&self.stdout).into_owned()
+    }
+
+    pub fn stderr_lossy(&self) -> String {
+        String::from_utf8_lossy(&self.stderr).into_owned()
+    }
+}
+
+impl GitBare {
+    pub fn git_command(
+        &self,
+        args: Vec<String>,
+    ) -> GitResult<GitCommandOutput> {
+        self.git_command_with(GitCommandParams::new(args))
+    }
+
+    pub fn git_command_with(
+        &self,
+        params: GitCommandParams,
+    ) -> GitResult<GitCommandOutput> {
+        let bare_dir = self.safe_bare_dir()?;
+        validate_git_command(&params)?;
+
+        let mut args = Vec::with_capacity(params.args.len() + 2);
+        args.push(OsString::from("--git-dir"));
+        args.push(bare_dir.as_os_str().to_os_string());
+        args.extend(params.args.iter().map(OsString::from));
+
+        let mut expression = duct::cmd("git", args)
+            .dir(&bare_dir)
+            .stdout_capture()
+            .stderr_capture()
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_TERMINAL_PROMPT", "0")
+            .env_remove("GIT_DIR")
+            .env_remove("GIT_WORK_TREE")
+            .env_remove("GIT_INDEX_FILE")
+            .env_remove("GIT_OBJECT_DIRECTORY")
+            .env_remove("GIT_ALTERNATE_OBJECT_DIRECTORIES")
+            .env_remove("GIT_SSH")
+            .env_remove("GIT_SSH_COMMAND")
+            .unchecked();
+
+        for (name, value) in &params.env {
+            expression = expression.env(name, value);
+        }
+
+        if let Some(stdin) = params.stdin {
+            expression = expression.stdin_bytes(stdin);
+        }
+
+        let output = expression.run()?;
+        let result = GitCommandOutput {
+            status_code: output.status.code(),
+            success: output.status.success(),
+            stdout: output.stdout,
+            stderr: output.stderr,
+        };
+
+        if params.check_status && !result.success {
+            return Err(GitError::CommandFailed {
+                status_code: result.status_code,
+                stderr: result.stderr_lossy(),
+            });
+        }
+
+        Ok(result)
+    }
+
+    pub fn git_command_stdout(&self, args: Vec<String>) -> GitResult<String> {
+        let output = self.git_command(args)?;
+        Ok(output.stdout_lossy())
+    }
+
+    pub fn git_command_success(&self, args: Vec<String>) -> GitResult<bool> {
+        let output =
+            self.git_command_with(GitCommandParams::new(args).unchecked())?;
+        Ok(output.success)
+    }
+
+    pub fn git_command_trusted(
+        &self,
+        args: Vec<String>,
+    ) -> GitResult<GitCommandOutput> {
+        self.git_command_with(GitCommandParams::new(args).trusted())
+    }
+
+    pub fn git_command_trusted_unchecked(
+        &self,
+        args: Vec<String>,
+    ) -> GitResult<GitCommandOutput> {
+        self.git_command_with(GitCommandParams::new(args).trusted().unchecked())
+    }
+
+    pub fn git_command_trusted_stdout(
+        &self,
+        args: Vec<String>,
+    ) -> GitResult<String> {
+        let output =
+            self.git_command_with(GitCommandParams::new(args).trusted())?;
+        Ok(output.stdout_lossy())
+    }
+
+    pub fn git_command_trusted_success(
+        &self,
+        args: Vec<String>,
+    ) -> GitResult<bool> {
+        let output = self.git_command_with(
+            GitCommandParams::new(args).trusted().unchecked(),
+        )?;
+        Ok(output.success)
+    }
+
+    fn safe_bare_dir(&self) -> GitResult<PathBuf> {
+        let bare_dir = self.bare_dir.canonicalize()?;
+        if !bare_dir.is_dir() {
+            return Err(GitError::NotBareRepository);
+        }
+
+        Ok(bare_dir)
+    }
+}
+
+fn validate_git_command(params: &GitCommandParams) -> GitResult<()> {
+    if params.bypass_subcommand_validation {
+        return Ok(());
+    }
+
+    if params.args.is_empty() {
+        return Err(GitError::UnsafeCommand(
+            "missing git subcommand".to_owned(),
+        ));
+    }
+
+    let subcommand = first_subcommand(&params.args).ok_or_else(|| {
+        GitError::UnsafeCommand("missing git subcommand".to_owned())
+    })?;
+
+    if DANGEROUS_SUBCOMMANDS.contains(&subcommand.as_str()) {
+        return Err(GitError::UnsafeCommand(format!(
+            "subcommand `{subcommand}` is not allowed"
+        )));
+    }
+
+    for arg in &params.args {
+        validate_git_arg(arg)?;
+    }
+
+    for (name, value) in &params.env {
+        validate_git_env(name, value)?;
+    }
+
+    Ok(())
+}
+
+fn first_subcommand(args: &[String]) -> Option<String> {
+    let mut iter = args.iter().peekable();
+    while let Some(arg) = iter.next() {
+        if arg == "--" {
+            return None;
+        }
+
+        if arg == "-c"
+            || arg == "-C"
+            || arg == "--git-dir"
+            || arg == "--work-tree"
+        {
+            iter.next();
+            continue;
+        }
+
+        if arg.starts_with('-') {
+            continue;
+        }
+
+        return Some(arg.to_owned());
+    }
+
+    None
+}
+
+fn validate_git_arg(arg: &str) -> GitResult<()> {
+    if DANGEROUS_OPTIONS.contains(&arg) {
+        return Err(GitError::UnsafeCommand(format!(
+            "option `{arg}` is not allowed"
+        )));
+    }
+
+    if DANGEROUS_OPTION_PREFIXES
+        .iter()
+        .any(|prefix| arg.starts_with(prefix))
+    {
+        return Err(GitError::UnsafeCommand(format!(
+            "option `{arg}` is not allowed"
+        )));
+    }
+
+    if let Some((name, value)) = arg.split_once('=') {
+        if looks_like_path(value) {
+            validate_relative_path(value).map_err(|_| {
+                GitError::UnsafeCommand(format!(
+                    "path value for `{name}` escapes bare_dir"
+                ))
+            })?;
+        }
+    } else if looks_like_path(arg) {
+        validate_relative_path(arg).map_err(|_| {
+            GitError::UnsafeCommand(format!(
+                "path argument `{arg}` escapes bare_dir"
+            ))
+        })?;
+    }
+
+    if contains_shell_metachar(arg) {
+        return Err(GitError::UnsafeCommand(format!(
+            "argument `{arg}` contains shell metacharacters"
+        )));
+    }
+
+    Ok(())
+}
+
+fn validate_git_env(name: &str, value: &str) -> GitResult<()> {
+    let upper_name = name.to_ascii_uppercase();
+    if DENIED_ENV_NAMES.contains(&upper_name.as_str())
+        || upper_name.starts_with("GIT_CONFIG_")
+    {
+        return Err(GitError::UnsafeCommand(format!(
+            "environment variable `{name}` is not allowed"
+        )));
+    }
+
+    if looks_like_path(value) {
+        validate_relative_path(value).map_err(|_| {
+            GitError::UnsafeCommand(format!(
+                "environment variable `{name}` escapes bare_dir"
+            ))
+        })?;
+    }
+
+    Ok(())
+}
+
+fn looks_like_path(value: &str) -> bool {
+    value.contains('/') || value.contains('\\') || value == "." || value == ".."
+}
+
+fn validate_relative_path(value: &str) -> Result<(), ()> {
+    let path = Path::new(value);
+    if path.is_absolute() {
+        return Err(());
+    }
+
+    for component in path.components() {
+        match component {
+            Component::Normal(part) if is_safe_path_part(part) => {}
+            Component::CurDir => {}
+            _ => return Err(()),
+        }
+    }
+
+    Ok(())
+}
+
+fn is_safe_path_part(part: &OsStr) -> bool {
+    let Some(part) = part.to_str() else {
+        return false;
+    };
+
+    !part.is_empty() && part != "." && part != ".."
+}
+
+fn contains_shell_metachar(value: &str) -> bool {
+    value.chars().any(|ch| {
+        matches!(ch, ';' | '|' | '&' | '`' | '$' | '<' | '>' | '\n' | '\r')
+    })
+}
diff --git a/lib/git/cmd/commit/commit_cherry_pick.rs b/lib/git/cmd/commit/commit_cherry_pick.rs
new file mode 100644
index 0000000..2179e10
--- /dev/null
+++ b/lib/git/cmd/commit/commit_cherry_pick.rs
@@ -0,0 +1,186 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        commit::CommitSignature, oid::ObjectId, parse::format_git_timestamp,
+    },
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Deserialize, Debug, Serialize)]
+pub struct CommitCherryPickParams {
+    pub cherrypick_oid: ObjectId,
+    pub author: CommitSignature,
+    pub committer: CommitSignature,
+    pub message: Option<String>,
+    pub mainline: u32,
+    pub update_ref: Option<String>,
+}
+
+#[derive(Clone, Deserialize, Debug, Serialize)]
+pub struct CommitCherryPickSequence {
+    pub cherrypick_oids: Vec<ObjectId>,
+    pub author: CommitSignature,
+    pub committer: CommitSignature,
+    pub update_ref: Option<String>,
+}
+
+impl GitBare {
+    pub fn commit_pick(
+        &self,
+        params: CommitCherryPickParams,
+    ) -> GitResult<ObjectId> {
+        let cherry_info = self.commit_info(params.cherrypick_oid.clone())?;
+        let their_tree = cherry_info.tree_id;
+        let repo = self.gix_repo()?;
+        let head_id =
+            repo.head_id().map_err(|e| GitError::Gix(e.to_string()))?;
+        let head_oid = ObjectId::new(head_id.detach().to_hex().to_string());
+        let head_info = self.commit_info(head_oid.clone())?;
+        let our_tree = head_info.tree_id;
+        let base_result =
+            self.merge_base(head_oid.clone(), params.cherrypick_oid.clone());
+        let base_tree = match base_result {
+            Ok(base_oid) => {
+                let base_info = self.commit_info(base_oid)?;
+                base_info.tree_id.as_str().to_string()
+            }
+            Err(_) => {
+                let empty_tree = "4b825dc642cb6eb9a060e54bf899d15363c725d7";
+                let empty_tree_gix_id: gix::hash::ObjectId =
+                    gix::hash::ObjectId::from_hex(empty_tree.as_bytes())
+                        .map_err(|e| GitError::Gix(e.to_string()))?;
+                if repo.has_object(empty_tree_gix_id) {
+                    empty_tree.to_string()
+                } else {
+                    let mktree_output =
+                        self.git_command_trusted_stdout(vec![
+                            "mktree".to_string(),
+                        ])?;
+                    mktree_output.trim().to_string()
+                }
+            }
+        };
+        let merge_tree_args = vec![
+            "merge-tree".to_string(),
+            "--write-tree".to_string(),
+            "--merge-base".to_string(),
+            base_tree.clone(),
+            our_tree.as_str().to_string(),
+            their_tree.as_str().to_string(),
+        ];
+
+        let merge_output = self.git_command_trusted(merge_tree_args);
+
+        let merged_tree_id = match merge_output {
+            Ok(output) => {
+                if output.success {
+                    ObjectId::new(output.stdout_lossy().trim())
+                } else {
+                    return Err(GitError::CommandFailed {
+                        status_code: output.status_code,
+                        stderr: output.stderr_lossy(),
+                    });
+                }
+            }
+            Err(err) => return Err(err),
+        };
+        let message = params
+            .message
+            .clone()
+            .unwrap_or(cherry_info.message.clone());
+        let mut commit_args = vec![
+            "commit-tree".to_string(),
+            merged_tree_id.as_str().to_string(),
+            "-p".to_string(),
+            head_oid.as_str().to_string(),
+        ];
+        if cherry_info.parent_ids.len() > 1 {
+            commit_args.push("-m".to_string());
+            commit_args.push(format!(
+                "cherry picked from commit {}",
+                params.cherrypick_oid.as_str()
+            ));
+            if params.mainline > 0 {
+                commit_args.push(format!("(mainline {})", params.mainline));
+            }
+        }
+        let cmd_params =
+            crate::cmd::command::GitCommandParams::new(commit_args)
+                .trusted()
+                .with_env(
+                    "GIT_AUTHOR_NAME".to_string(),
+                    params.author.name.clone(),
+                )
+                .with_env(
+                    "GIT_AUTHOR_EMAIL".to_string(),
+                    params.author.email.clone(),
+                )
+                .with_env(
+                    "GIT_AUTHOR_DATE".to_string(),
+                    format_git_timestamp(
+                        params.author.time_secs,
+                        params.author.offset_minutes,
+                    ),
+                )
+                .with_env(
+                    "GIT_COMMITTER_NAME".to_string(),
+                    params.committer.name.clone(),
+                )
+                .with_env(
+                    "GIT_COMMITTER_EMAIL".to_string(),
+                    params.committer.email.clone(),
+                )
+                .with_env(
+                    "GIT_COMMITTER_DATE".to_string(),
+                    format_git_timestamp(
+                        params.committer.time_secs,
+                        params.committer.offset_minutes,
+                    ),
+                )
+                .with_stdin(message.as_bytes().to_vec());
+        let commit_output = self.git_command_with(cmd_params)?;
+
+        if !commit_output.success {
+            return Err(GitError::CommandFailed {
+                status_code: commit_output.status_code,
+                stderr: commit_output.stderr_lossy(),
+            });
+        }
+
+        let new_oid = ObjectId::new(commit_output.stdout_lossy().trim());
+        if let Some(ref_name) = &params.update_ref {
+            self.git_command_trusted(vec![
+                "update-ref".to_string(),
+                ref_name.clone(),
+                new_oid.as_str().to_string(),
+            ])?;
+        }
+
+        Ok(new_oid)
+    }
+    pub fn commit_cherry_pick_sequence(
+        &self,
+        params: CommitCherryPickSequence,
+    ) -> GitResult<ObjectId> {
+        let mut last_oid: Option<ObjectId> = None;
+
+        for cherry_oid in params.cherrypick_oids {
+            let pick_params = CommitCherryPickParams {
+                cherrypick_oid: cherry_oid,
+                author: params.author.clone(),
+                committer: params.committer.clone(),
+                message: None, // Use original commit message
+                mainline: 1,   // Default mainline
+                update_ref: params.update_ref.clone(),
+            };
+
+            last_oid = Some(self.commit_pick(pick_params)?);
+        }
+
+        last_oid.ok_or_else(|| {
+            GitError::ParseError("cherry-pick sequence was empty".to_string())
+        })
+    }
+}
diff --git a/lib/git/cmd/commit/commit_create.rs b/lib/git/cmd/commit/commit_create.rs
new file mode 100644
index 0000000..a35c357
--- /dev/null
+++ b/lib/git/cmd/commit/commit_create.rs
@@ -0,0 +1,234 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{command::GitCommandParams, oid::ObjectId},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FileChange {
+    pub path: String,
+    pub content: Vec<u8>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CreateCommitParams {
+    pub branch: String,
+    pub message: String,
+    pub author_name: String,
+    pub author_email: String,
+    pub committer_name: String,
+    pub committer_email: String,
+    pub files: Vec<FileChange>,
+}
+
+#[derive(Debug, Clone)]
+struct TreeEntry {
+    mode: String,   // e.g. "100644"
+    kind: String,   // "blob" or "tree"
+    oid: ObjectId,
+    path: String,
+}
+
+impl GitBare {
+    /// Create a commit with the given file changes on the specified branch.
+    ///
+    /// Returns the OID of the newly created commit.
+    pub fn commit_create(
+        &self,
+        params: CreateCommitParams,
+    ) -> GitResult<ObjectId> {
+        let repo = self.gix_repo()?;
+
+        // 1. Write each file as a blob and collect entries
+        let mut new_entries: Vec<TreeEntry> = Vec::with_capacity(params.files.len());
+        for fc in &params.files {
+            let blob_upload_result = self.blob_upload(crate::cmd::blob::BlobUploadParams {
+                blob: fc.content.clone(),
+                path: fc.path.clone(),
+            })?;
+            new_entries.push(TreeEntry {
+                mode: "100644".to_string(),
+                kind: "blob".to_string(),
+                oid: blob_upload_result.id,
+                path: fc.path.clone(),
+            });
+        }
+
+        // 2. Get the parent commit (HEAD of the branch, or initial commit)
+        let parent_oid: Option<ObjectId>;
+        let existing_tree_entries: Vec<TreeEntry>;
+
+        let branch_ref = format!("refs/heads/{}", params.branch);
+
+        match repo.find_reference(&branch_ref) {
+            Ok(r) => {
+                let oid = r.into_fully_peeled_id()
+                    .map_err(|e| GitError::Gix(e.to_string()))?
+                    .detach();
+                let oid_str = oid.to_hex().to_string();
+                let commit_oid = ObjectId::new(oid_str);
+                let commit = self.commit_info(commit_oid.clone())?;
+
+                let tree_entries = self._ls_tree(commit.tree_id)?;
+                parent_oid = Some(commit_oid);
+                existing_tree_entries = tree_entries;
+            }
+            Err(_) => {
+                parent_oid = None;
+                existing_tree_entries = Vec::new();
+            }
+        }
+
+        // 3. Merge new entries into existing tree (replace by path)
+        let mut merged: Vec<TreeEntry> = Vec::new();
+        let mut seen_paths: std::collections::HashSet<String> =
+            std::collections::HashSet::new();
+
+        for entry in new_entries {
+            seen_paths.insert(entry.path.clone());
+            merged.push(entry);
+        }
+        for entry in existing_tree_entries {
+            if !seen_paths.contains(&entry.path) {
+                merged.push(entry);
+            }
+        }
+
+        // 4. Create tree with git mktree
+        let tree_oid = self._mktree(&merged)?;
+
+        // 5. Create commit with git commit-tree
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs() as i64;
+        let timestamp = crate::cmd::parse::format_git_timestamp(now, 0);
+
+        let mut commit_tree_args = vec![
+            "commit-tree".to_string(),
+            tree_oid.as_str().to_string(),
+        ];
+        if let Some(parent) = &parent_oid {
+            commit_tree_args.push("-p".to_string());
+            commit_tree_args.push(parent.as_str().to_string());
+        }
+        commit_tree_args.push("-F".to_string());
+        commit_tree_args.push("-".to_string());
+
+        let commit_output = self.git_command_with(
+            GitCommandParams::new(commit_tree_args)
+                .with_stdin(params.message.as_bytes().to_vec())
+                .with_env("GIT_AUTHOR_NAME".to_string(), params.author_name.clone())
+                .with_env("GIT_AUTHOR_EMAIL".to_string(), params.author_email.clone())
+                .with_env("GIT_AUTHOR_DATE".to_string(), timestamp.clone())
+                .with_env("GIT_COMMITTER_NAME".to_string(), params.committer_name.clone())
+                .with_env("GIT_COMMITTER_EMAIL".to_string(), params.committer_email.clone())
+                .with_env("GIT_COMMITTER_DATE".to_string(), timestamp),
+        )?;
+
+        if !commit_output.success {
+            return Err(GitError::CommandFailed {
+                status_code: commit_output.status_code,
+                stderr: commit_output.stderr_lossy(),
+            });
+        }
+
+        let stdout_str = commit_output.stdout_lossy();
+        let commit_oid_str = stdout_str.trim();
+        if commit_oid_str.is_empty() {
+            return Err(GitError::CommandFailed {
+                status_code: commit_output.status_code,
+                stderr: "no commit OID produced".to_string(),
+            });
+        }
+
+        let commit_oid = ObjectId::new(commit_oid_str);
+
+        // 6. Update the branch ref
+        let update_ref_args = vec![
+            "update-ref".to_string(),
+            branch_ref,
+            commit_oid.as_str().to_string(),
+        ];
+        let _update_output = self.git_command_with(
+            GitCommandParams::new(update_ref_args),
+        )?;
+
+        Ok(commit_oid)
+    }
+
+    /// List tree entries (mode, type, oid, path) using git ls-tree.
+    fn _ls_tree(&self, tree_oid: ObjectId) -> GitResult<Vec<TreeEntry>> {
+        let output = self.git_command_with(GitCommandParams::new(vec![
+            "ls-tree".to_string(),
+            tree_oid.as_str().to_string(),
+        ]))?;
+
+        if !output.success {
+            return Err(GitError::CommandFailed {
+                status_code: output.status_code,
+                stderr: output.stderr_lossy(),
+            });
+        }
+
+        let stdout = output.stdout_lossy();
+        let mut entries = Vec::new();
+
+        for line in stdout.lines() {
+            let line = line.trim();
+            if line.is_empty() {
+                continue;
+            }
+            // Output format: <mode> <type> <oid>\t<path>
+            let parts: Vec<&str> = line.splitn(2, '\t').collect();
+            if parts.len() < 2 {
+                continue;
+            }
+            let meta: Vec<&str> = parts[0].split_whitespace().collect();
+            if meta.len() < 3 {
+                continue;
+            }
+            entries.push(TreeEntry {
+                mode: meta[0].to_string(),
+                kind: meta[1].to_string(),
+                oid: ObjectId::new(meta[2]),
+                path: parts[1].to_string(),
+            });
+        }
+
+        Ok(entries)
+    }
+
+    /// Create a tree object from entries using git mktree.
+    fn _mktree(&self, entries: &[TreeEntry]) -> GitResult<ObjectId> {
+        // Build input for git mktree:
+        // Each line: <mode> <type> <oid>\t<path>
+        let mut input = String::new();
+        for entry in entries {
+            input.push_str(&format!(
+                "{} {} {}\t{}\n",
+                entry.mode, entry.kind, entry.oid.as_str(), entry.path
+            ));
+        }
+
+        let output = self.git_command_with(
+            GitCommandParams::new(vec![
+                "mktree".to_string(),
+            ])
+            .with_stdin(input.into_bytes()),
+        )?;
+
+        if !output.success {
+            return Err(GitError::CommandFailed {
+                status_code: output.status_code,
+                stderr: output.stderr_lossy(),
+            });
+        }
+
+        let stdout = output.stdout_lossy();
+        let oid_str = stdout.trim();
+        Ok(ObjectId::new(oid_str))
+    }
+}
diff --git a/lib/git/cmd/commit/commit_history.rs b/lib/git/cmd/commit/commit_history.rs
new file mode 100644
index 0000000..8aea12e
--- /dev/null
+++ b/lib/git/cmd/commit/commit_history.rs
@@ -0,0 +1,31 @@
+use crate::{
+    bare::GitBare,
+    cmd::{
+        commit::{
+            CommitMeta,
+            commit_walker::{CommitWalkParams, CommitWalkSort},
+        },
+        oid::ObjectId,
+    },
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn commit_history(
+        &self,
+        params: CommitWalkParams,
+    ) -> GitResult<Vec<CommitMeta>> {
+        self.commit_walk(params)
+    }
+
+    pub fn commit_history_head(
+        &self,
+        limit: Option<usize>,
+    ) -> GitResult<Vec<CommitMeta>> {
+        let mut params = CommitWalkParams::default();
+        params.start_oids = vec![ObjectId::new("HEAD")];
+        params.limit = limit;
+        params.sort = CommitWalkSort::Time;
+        self.commit_history(params)
+    }
+}
diff --git a/lib/git/cmd/commit/commit_info.rs b/lib/git/cmd/commit/commit_info.rs
new file mode 100644
index 0000000..4fcc9fc
--- /dev/null
+++ b/lib/git/cmd/commit/commit_info.rs
@@ -0,0 +1,72 @@
+use crate::{
+    bare::GitBare,
+    cmd::{
+        commit::{CommitMeta, CommitSignature},
+        oid::ObjectId,
+    },
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn commit_info(&self, oid: ObjectId) -> GitResult<CommitMeta> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+
+        let commit = repo.find_commit(gix_id)?;
+        let decoded = commit.decode()?;
+
+        let message_raw = commit.message_raw()?;
+        let message = message_raw.to_string();
+        let message = message.trim_end_matches('\n').to_string();
+        let summary = message.lines().next().unwrap_or("").to_string();
+
+        let author_sig = decoded.author()?;
+        let author_time = author_sig.time()?;
+        let committer_sig = decoded.committer()?;
+        let committer_time = committer_sig.time()?;
+
+        let tree_id = ObjectId::new(decoded.tree().to_hex().to_string());
+        let parent_ids: Vec<ObjectId> = decoded
+            .parents()
+            .map(|id| ObjectId::new(id.to_hex().to_string()))
+            .collect();
+
+        let encoding = decoded
+            .extra_headers()
+            .find("encoding")
+            .map(|v| v.to_string());
+
+        Ok(CommitMeta {
+            oid,
+            message,
+            summary,
+            author: CommitSignature {
+                name: author_sig.name.to_string(),
+                email: author_sig.email.to_string(),
+                time_secs: author_time.seconds as i64,
+                offset_minutes: (author_time.offset / 60) as i32,
+            },
+            committer: CommitSignature {
+                name: committer_sig.name.to_string(),
+                email: committer_sig.email.to_string(),
+                time_secs: committer_time.seconds as i64,
+                offset_minutes: (committer_time.offset / 60) as i32,
+            },
+            tree_id,
+            parent_ids,
+            encoding,
+        })
+    }
+
+    pub fn commit_exists(&self, oid: ObjectId) -> GitResult<bool> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+
+        if !repo.has_object(gix_id) {
+            return Ok(false);
+        }
+
+        let header = repo.find_header(gix_id)?;
+        Ok(header.kind() == gix::object::Kind::Commit)
+    }
+}
diff --git a/lib/git/cmd/commit/commit_prefix.rs b/lib/git/cmd/commit/commit_prefix.rs
new file mode 100644
index 0000000..ea7c027
--- /dev/null
+++ b/lib/git/cmd/commit/commit_prefix.rs
@@ -0,0 +1,25 @@
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn commit_oid_from_prefix(&self, prefix: &str) -> GitResult<ObjectId> {
+        let repo = self.gix_repo()?;
+        let id = repo
+            .rev_parse_single(prefix)
+            .map_err(|_| GitError::ObjectNotFound(prefix.to_string()))?;
+
+        let obj_id = id.detach();
+        Ok(ObjectId::new(obj_id.to_hex().to_string()))
+    }
+
+    pub fn commit_info_from_prefix(
+        &self,
+        prefix: &str,
+    ) -> GitResult<crate::cmd::commit::CommitMeta> {
+        let oid = self.commit_oid_from_prefix(prefix)?;
+        self.commit_info(oid)
+    }
+}
diff --git a/lib/git/cmd/commit/commit_refs.rs b/lib/git/cmd/commit/commit_refs.rs
new file mode 100644
index 0000000..42839e4
--- /dev/null
+++ b/lib/git/cmd/commit/commit_refs.rs
@@ -0,0 +1,50 @@
+use crate::{
+    bare::GitBare,
+    cmd::{commit::CommitRefInfo, oid::ObjectId},
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn commit_refs(&self, oid: ObjectId) -> GitResult<Vec<CommitRefInfo>> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+        let target_hex = gix_id.to_hex().to_string();
+
+        let mut refs = Vec::new();
+
+        let platform = repo.references()?;
+        let iter = platform.all()?;
+
+        for ref_result in iter {
+            let reference = ref_result?;
+            let full_name = reference.name().as_bstr().to_string();
+
+            let is_branch = full_name.starts_with("refs/heads/");
+            let is_tag = full_name.starts_with("refs/tags/");
+            let is_remote = full_name.starts_with("refs/remotes/");
+
+            if !is_branch && !is_tag && !is_remote {
+                continue;
+            }
+
+            let target = reference.target();
+            let target_id = target.try_id().ok_or_else(|| {
+                crate::errors::GitError::Internal(
+                    "ref has no direct target".to_string(),
+                )
+            })?;
+
+            if target_id.to_hex().to_string() == target_hex {
+                let short_name = reference.name().shorten();
+                refs.push(CommitRefInfo {
+                    name: short_name.to_string(),
+                    target: oid.clone(),
+                    is_remote,
+                    is_tag,
+                });
+            }
+        }
+
+        Ok(refs)
+    }
+}
diff --git a/lib/git/cmd/commit/commit_summary.rs b/lib/git/cmd/commit/commit_summary.rs
new file mode 100644
index 0000000..a8fda2f
--- /dev/null
+++ b/lib/git/cmd/commit/commit_summary.rs
@@ -0,0 +1,41 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{commit::CommitMeta, oid::ObjectId},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitSummary {
+    pub head: Option<CommitMeta>,
+    pub count: usize,
+}
+
+impl GitBare {
+    pub fn commit_summary(&self) -> GitResult<CommitSummary> {
+        let repo = self.gix_repo()?;
+        let head_id = repo
+            .head_id()
+            .map_err(|_| GitError::RefNotFound("HEAD".to_string()));
+        let head_id = match head_id {
+            Ok(id) => id,
+            Err(_) => {
+                return Ok(CommitSummary {
+                    head: None,
+                    count: 0,
+                });
+            }
+        };
+
+        let head_oid = ObjectId::new(head_id.detach().to_hex().to_string());
+        let head_commit = self.commit_info(head_oid)?;
+        let walk = repo.rev_walk([head_id.detach()]).all()?;
+        let count = walk.count();
+
+        Ok(CommitSummary {
+            head: Some(head_commit),
+            count,
+        })
+    }
+}
diff --git a/lib/git/cmd/commit/commit_walker.rs b/lib/git/cmd/commit/commit_walker.rs
new file mode 100644
index 0000000..0d7629d
--- /dev/null
+++ b/lib/git/cmd/commit/commit_walker.rs
@@ -0,0 +1,147 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{commit::CommitMeta, oid::ObjectId},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum CommitWalkSort {
+    None,
+    Topological,
+    Time,
+    Reverse,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitWalkParams {
+    pub start_oids: Vec<ObjectId>,
+    pub hide_oids: Vec<ObjectId>,
+    pub limit: Option<usize>,
+    pub skip: usize,
+    pub first_parent: bool,
+    pub sort: CommitWalkSort,
+    pub branch: Option<String>,
+}
+
+impl Default for CommitWalkParams {
+    fn default() -> Self {
+        Self {
+            start_oids: Vec::new(),
+            hide_oids: Vec::new(),
+            limit: None,
+            skip: 0,
+            first_parent: false,
+            sort: CommitWalkSort::Time,
+            branch: None,
+        }
+    }
+}
+
+impl GitBare {
+    pub fn commit_walk(
+        &self,
+        params: CommitWalkParams,
+    ) -> GitResult<Vec<CommitMeta>> {
+        let repo = self.gix_repo()?;
+        let tips: Vec<gix::hash::ObjectId> = if let Some(ref branch_name) = params.branch {
+            if branch_name.is_empty() {
+                vec![repo.head_id()?.detach()]
+            } else {
+                let ref_name = format!("refs/heads/{branch_name}");
+                match repo.try_find_reference(&ref_name)? {
+                    Some(reference) => {
+                        let target = reference.target();
+                        let target_id = target.try_id().ok_or_else(|| {
+                            GitError::Internal(format!("branch '{branch_name}' has no direct target"))
+                        })?;
+                        vec![target_id.to_owned()]
+                    }
+                    None => {
+                        let remote_ref = format!("refs/remotes/{branch_name}");
+                        match repo.try_find_reference(&remote_ref)? {
+                            Some(reference) => {
+                                let target = reference.target();
+                                let target_id = target.try_id().ok_or_else(|| {
+                                    GitError::Internal(format!("remote branch '{branch_name}' has no direct target"))
+                                })?;
+                                vec![target_id.to_owned()]
+                            }
+                            None => {
+                                return Err(GitError::RefNotFound(branch_name.clone()));
+                            }
+                        }
+                    }
+                }
+            }
+        } else if params.start_oids.is_empty() {
+            vec![repo.head_id()?.detach()]
+        } else {
+            params
+                .start_oids
+                .iter()
+                .map(|oid| oid.try_into())
+                .collect::<Result<Vec<_>, _>>()?
+        };
+        let hide: Vec<gix::hash::ObjectId> = params
+            .hide_oids
+            .iter()
+            .map(|oid| oid.try_into())
+            .collect::<Result<Vec<_>, _>>()?;
+        let mut platform = repo.rev_walk(tips);
+        match params.sort {
+            CommitWalkSort::None => {}
+            CommitWalkSort::Topological => {
+                platform = platform
+                    .sorting(gix::revision::walk::Sorting::BreadthFirst);
+            }
+            CommitWalkSort::Time => {
+                platform = platform.sorting(gix::revision::walk::Sorting::ByCommitTime(
+                    gix::traverse::commit::simple::CommitTimeOrder::NewestFirst,
+                ));
+            }
+            CommitWalkSort::Reverse => {
+                platform = platform.sorting(gix::revision::walk::Sorting::ByCommitTime(
+                    gix::traverse::commit::simple::CommitTimeOrder::OldestFirst,
+                ));
+            }
+        }
+        if params.first_parent {
+            platform = platform.first_parent_only();
+        }
+        if !hide.is_empty() {
+            platform = platform.with_boundary(hide);
+        }
+
+        let walk = platform.all()?;
+
+        let mut commits = Vec::new();
+        let mut count = 0;
+        let skip = params.skip;
+
+        for info in walk {
+            if count < skip {
+                count += 1;
+                continue;
+            }
+
+            let info = info?;
+            let oid = ObjectId::new(info.id().detach().to_hex().to_string());
+            let commit = self.commit_info(oid)?;
+            commits.push(commit);
+            if let Some(limit) = params.limit {
+                if commits.len() >= limit {
+                    break;
+                }
+            }
+
+            count += 1;
+        }
+        if matches!(params.sort, CommitWalkSort::Reverse) {
+            commits.reverse();
+        }
+
+        Ok(commits)
+    }
+}
diff --git a/lib/git/cmd/commit/mod.rs b/lib/git/cmd/commit/mod.rs
new file mode 100644
index 0000000..79c834a
--- /dev/null
+++ b/lib/git/cmd/commit/mod.rs
@@ -0,0 +1,46 @@
+use serde::{Deserialize, Serialize};
+
+use crate::cmd::oid::ObjectId;
+
+pub mod commit_cherry_pick;
+pub mod commit_create;
+pub mod commit_history;
+pub mod commit_info;
+pub mod commit_prefix;
+pub mod commit_refs;
+pub mod commit_summary;
+pub mod commit_walker;
+pub use commit_cherry_pick::{
+    CommitCherryPickParams, CommitCherryPickSequence,
+};
+pub use commit_create::{CreateCommitParams, FileChange};
+pub use commit_summary::CommitSummary;
+pub use commit_walker::{CommitWalkParams, CommitWalkSort};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitSignature {
+    pub name: String,
+    pub email: String,
+    pub time_secs: i64,
+    pub offset_minutes: i32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitMeta {
+    pub oid: ObjectId,
+    pub message: String,
+    pub summary: String,
+    pub author: CommitSignature,
+    pub committer: CommitSignature,
+    pub tree_id: ObjectId,
+    pub parent_ids: Vec<ObjectId>,
+    pub encoding: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitRefInfo {
+    pub name: String,
+    pub target: ObjectId,
+    pub is_remote: bool,
+    pub is_tag: bool,
+}
diff --git a/lib/git/cmd/diff/diff_index_to_tree.rs b/lib/git/cmd/diff/diff_index_to_tree.rs
new file mode 100644
index 0000000..df1b1f4
--- /dev/null
+++ b/lib/git/cmd/diff/diff_index_to_tree.rs
@@ -0,0 +1,152 @@
+use gix::bstr::ByteSlice;
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        diff::{
+            DiffOptions, DiffResult, DiffStats,
+            diff_tree_to_tree::{
+                HunkCollector, change_to_delta, matches_pathspec,
+            },
+        },
+        oid::ObjectId,
+    },
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn diff_index_to_tree(
+        &self,
+        tree: ObjectId,
+        opts: Option<DiffOptions>,
+    ) -> GitResult<DiffResult> {
+        let options = opts.unwrap_or_default();
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&tree).try_into()?;
+        let tree_obj = if let Ok(tree) = repo.find_tree(gix_id) {
+            tree
+        } else {
+            let commit = repo
+                .find_commit(gix_id)
+                .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+            let tree_id = commit
+                .tree_id()
+                .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?
+                .detach();
+            repo.find_tree(tree_id)
+                .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?
+        };
+        let head_id = repo
+            .head_id()
+            .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+        let head_commit = repo
+            .find_commit(head_id.detach())
+            .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+        let head_tree_id = head_commit
+            .tree_id()
+            .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?
+            .detach();
+        let head_tree = repo
+            .find_tree(head_tree_id)
+            .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+        let tree_oid = tree_obj.id().detach();
+        let head_tree_oid = head_tree.id().detach();
+        if tree_oid == head_tree_oid {
+            return Ok(DiffResult {
+                stats: DiffStats {
+                    files_changed: 0,
+                    insertions: 0,
+                    deletions: 0,
+                },
+                deltas: Vec::new(),
+            });
+        }
+
+        let mut diff_opts = gix::diff::Options::default();
+        diff_opts.track_path();
+
+        let changes = repo
+            .diff_tree_to_tree(&tree_obj, &head_tree, Some(diff_opts))
+            .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+
+        let mut resource_cache = repo
+            .diff_resource_cache_for_tree_diff()
+            .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+
+        let mut deltas = Vec::new();
+        let mut stats = DiffStats {
+            files_changed: 0,
+            insertions: 0,
+            deletions: 0,
+        };
+
+        for change in &changes {
+            let location = change.location().to_str().unwrap_or("");
+            if !matches_pathspec(&options.pathspec, location) {
+                continue;
+            }
+
+            let mut delta = change_to_delta(change);
+
+            resource_cache
+                .set_resource_by_change(change.to_ref(), &repo.objects)
+                .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+
+            let is_binary = {
+                use gix::diff::blob::platform::prepare_diff::Operation;
+
+                let prep = resource_cache
+                    .prepare_diff()
+                    .map_err(|e| crate::errors::GitError::Gix(e.to_string()))?;
+
+                match prep.operation {
+                    Operation::InternalDiff { algorithm } => {
+                        let input = prep.interned_input();
+                        let diff = gix::diff::blob::diff_with_slider_heuristics(
+                            algorithm, &input,
+                        );
+
+                        stats.files_changed += 1;
+                        stats.insertions += diff.count_additions() as usize;
+                        stats.deletions += diff.count_removals() as usize;
+
+                        if options.context_lines > 0 {
+                            let ctx = gix::diff::blob::unified_diff::ContextSize::symmetrical(
+                                options.context_lines.max(3),
+                            );
+                            let collector = HunkCollector::new();
+                            let unified = gix::diff::blob::UnifiedDiff::new(
+                                &diff, &input, collector, ctx,
+                            );
+                            let (hunks, lines) =
+                                unified.consume().map_err(|e| {
+                                    crate::errors::GitError::Gix(e.to_string())
+                                })?;
+                            delta.hunks = hunks;
+                            delta.lines = lines;
+                        }
+                        false
+                    }
+                    Operation::SourceOrDestinationIsBinary => {
+                        stats.files_changed += 1;
+                        true
+                    }
+                    Operation::ExternalCommand { .. } => {
+                        stats.files_changed += 1;
+                        false
+                    }
+                }
+            };
+
+            if is_binary {
+                delta.old_file.is_binary = true;
+                delta.new_file.is_binary = true;
+            }
+
+            resource_cache.clear_resource_cache_keep_allocation();
+            deltas.push(delta);
+        }
+
+        Ok(DiffResult { stats, deltas })
+    }
+}
diff --git a/lib/git/cmd/diff/diff_patch.rs b/lib/git/cmd/diff/diff_patch.rs
new file mode 100644
index 0000000..57c1fdb
--- /dev/null
+++ b/lib/git/cmd/diff/diff_patch.rs
@@ -0,0 +1,366 @@
+use gix::{
+    bstr::ByteSlice,
+    diff::blob::unified_diff::{
+        ConsumeHunk, ContextSize, DiffLineKind, HunkHeader,
+    },
+};
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        diff::{
+            DiffDeltaStatus, DiffOptions, DiffResult, DiffStats,
+            SideBySideChangeType, SideBySideDiffResult, SideBySideFile,
+            SideBySideLine,
+            diff_tree_to_tree::{
+                HunkCollector, change_to_delta, matches_pathspec, peel_to_tree,
+            },
+        },
+        oid::ObjectId,
+    },
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn diff_patch(
+        &self,
+        old_commit: ObjectId,
+        new_commit: ObjectId,
+        opts: Option<DiffOptions>,
+    ) -> GitResult<DiffResult> {
+        let repo = self.gix_repo()?;
+        let options = opts.unwrap_or_default();
+        let context_lines = options.context_lines.max(3);
+
+        let old_tree_obj = peel_to_tree(&repo, old_commit)?;
+        let new_tree_obj = peel_to_tree(&repo, new_commit)?;
+
+        let mut diff_opts = gix::diff::Options::default();
+        diff_opts.track_path();
+
+        let changes = repo
+            .diff_tree_to_tree(&old_tree_obj, &new_tree_obj, Some(diff_opts))
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut resource_cache = repo
+            .diff_resource_cache_for_tree_diff()
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut deltas = Vec::new();
+        let mut stats = DiffStats {
+            files_changed: 0,
+            insertions: 0,
+            deletions: 0,
+        };
+
+        for change in &changes {
+            let location = change.location().to_str().unwrap_or("");
+            if !matches_pathspec(&options.pathspec, location) {
+                continue;
+            }
+
+            let mut delta = change_to_delta(change);
+
+            // Only diff blobs — skip trees (directories)
+            let entry_mode = change.entry_mode();
+            if entry_mode.is_tree() {
+                stats.files_changed += 1;
+                resource_cache.clear_resource_cache_keep_allocation();
+                deltas.push(delta);
+                continue;
+            }
+
+            resource_cache
+                .set_resource_by_change(change.to_ref(), &repo.objects)
+                .map_err(|e| GitError::Gix(e.to_string()))?;
+
+            let is_binary = {
+                use gix::diff::blob::platform::prepare_diff::Operation;
+
+                let prep = resource_cache
+                    .prepare_diff()
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+
+                match prep.operation {
+                    Operation::InternalDiff { algorithm } => {
+                        let input = prep.interned_input();
+                        let diff = gix::diff::blob::diff_with_slider_heuristics(
+                            algorithm, &input,
+                        );
+
+                        stats.files_changed += 1;
+                        stats.insertions += diff.count_additions() as usize;
+                        stats.deletions += diff.count_removals() as usize;
+
+                        let ctx = ContextSize::symmetrical(context_lines);
+                        let collector = HunkCollector::new();
+                        let unified = gix::diff::blob::UnifiedDiff::new(
+                            &diff, &input, collector, ctx,
+                        );
+                        let (hunks, lines) = unified
+                            .consume()
+                            .map_err(|e| GitError::Gix(e.to_string()))?;
+                        delta.hunks = hunks;
+                        delta.lines = lines;
+
+                        false
+                    }
+                    Operation::SourceOrDestinationIsBinary => {
+                        stats.files_changed += 1;
+                        true
+                    }
+                    Operation::ExternalCommand { .. } => {
+                        stats.files_changed += 1;
+                        false
+                    }
+                }
+            };
+
+            if is_binary {
+                delta.old_file.is_binary = true;
+                delta.new_file.is_binary = true;
+            }
+
+            resource_cache.clear_resource_cache_keep_allocation();
+            deltas.push(delta);
+        }
+
+        Ok(DiffResult { stats, deltas })
+    }
+
+    pub fn diff_patch_side_by_side(
+        &self,
+        old_commit: ObjectId,
+        new_commit: ObjectId,
+        opts: Option<DiffOptions>,
+    ) -> GitResult<SideBySideDiffResult> {
+        let repo = self.gix_repo()?;
+        let options = opts.unwrap_or_default();
+        let context_lines = options.context_lines.max(3);
+
+        let old_tree_obj = peel_to_tree(&repo, old_commit)?;
+        let new_tree_obj = peel_to_tree(&repo, new_commit)?;
+
+        let mut diff_opts = gix::diff::Options::default();
+        diff_opts.track_path();
+
+        let changes = repo
+            .diff_tree_to_tree(&old_tree_obj, &new_tree_obj, Some(diff_opts))
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut resource_cache = repo
+            .diff_resource_cache_for_tree_diff()
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut files: Vec<SideBySideFile> = Vec::new();
+        let mut total_additions = 0;
+        let mut total_deletions = 0;
+
+        for change in &changes {
+            let location = change.location().to_str().unwrap_or("");
+            if !matches_pathspec(&options.pathspec, location) {
+                continue;
+            }
+
+            let delta = change_to_delta(change);
+            let is_rename = delta.status == DiffDeltaStatus::Renamed;
+            let path = delta.new_file.path.clone().unwrap_or_default();
+
+            // Skip directories — only diff blobs
+            if change.entry_mode().is_tree() {
+                total_additions += 0;
+                total_deletions += 0;
+                files.push(SideBySideFile {
+                    path,
+                    additions: 0,
+                    deletions: 0,
+                    is_binary: false,
+                    is_rename,
+                    lines: Vec::new(),
+                });
+                resource_cache.clear_resource_cache_keep_allocation();
+                continue;
+            }
+
+            resource_cache
+                .set_resource_by_change(change.to_ref(), &repo.objects)
+                .map_err(|e| GitError::Gix(e.to_string()))?;
+
+            let (file_additions, file_deletions, is_binary, sbs_lines) = {
+                use gix::diff::blob::platform::prepare_diff::Operation;
+
+                let prep = resource_cache
+                    .prepare_diff()
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+
+                match prep.operation {
+                    Operation::InternalDiff { algorithm } => {
+                        let input = prep.interned_input();
+                        let diff = gix::diff::blob::diff_with_slider_heuristics(
+                            algorithm, &input,
+                        );
+
+                        let adds = diff.count_additions() as usize;
+                        let dels = diff.count_removals() as usize;
+
+                        let ctx = ContextSize::symmetrical(context_lines);
+                        let collector = SideBySideCollector::new();
+                        let unified = gix::diff::blob::UnifiedDiff::new(
+                            &diff, &input, collector, ctx,
+                        );
+                        let lines = unified
+                            .consume()
+                            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+                        (adds, dels, false, lines)
+                    }
+                    Operation::SourceOrDestinationIsBinary => {
+                        (0, 0, true, Vec::new())
+                    }
+                    Operation::ExternalCommand { .. } => {
+                        (0, 0, false, Vec::new())
+                    }
+                }
+            };
+
+            total_additions += file_additions;
+            total_deletions += file_deletions;
+
+            files.push(SideBySideFile {
+                path,
+                additions: file_additions,
+                deletions: file_deletions,
+                is_binary,
+                is_rename,
+                lines: sbs_lines,
+            });
+
+            resource_cache.clear_resource_cache_keep_allocation();
+        }
+
+        Ok(SideBySideDiffResult {
+            files,
+            total_additions,
+            total_deletions,
+        })
+    }
+}
+struct SideBySideCollector {
+    lines: Vec<SideBySideLine>,
+    pending_removed: Vec<(u32, String)>,
+    pending_added: Vec<(u32, String)>,
+    current_old_lineno: u32,
+    current_new_lineno: u32,
+}
+
+impl SideBySideCollector {
+    fn new() -> Self {
+        SideBySideCollector {
+            lines: Vec::new(),
+            pending_removed: Vec::new(),
+            pending_added: Vec::new(),
+            current_old_lineno: 0,
+            current_new_lineno: 0,
+        }
+    }
+
+    fn flush_pending(&mut self) {
+        let removed_count = self.pending_removed.len();
+        let added_count = self.pending_added.len();
+        let common = removed_count.min(added_count);
+
+        for i in 0..common {
+            let (left_no, old_content) = &self.pending_removed[i];
+            let (right_no, new_content) = &self.pending_added[i];
+
+            let change_type = if old_content == new_content {
+                SideBySideChangeType::Unchanged
+            } else {
+                SideBySideChangeType::Modified
+            };
+
+            self.lines.push(SideBySideLine {
+                left_line_no: Some(*left_no),
+                right_line_no: Some(*right_no),
+                left_content: old_content.clone(),
+                right_content: new_content.clone(),
+                change_type,
+            });
+        }
+
+        for i in common..removed_count {
+            let (left_no, old_content) = &self.pending_removed[i];
+            self.lines.push(SideBySideLine {
+                left_line_no: Some(*left_no),
+                right_line_no: None,
+                left_content: old_content.clone(),
+                right_content: String::new(),
+                change_type: SideBySideChangeType::Removed,
+            });
+        }
+
+        for i in common..added_count {
+            let (right_no, new_content) = &self.pending_added[i];
+            self.lines.push(SideBySideLine {
+                left_line_no: None,
+                right_line_no: Some(*right_no),
+                left_content: String::new(),
+                right_content: new_content.clone(),
+                change_type: SideBySideChangeType::Added,
+            });
+        }
+
+        self.pending_removed.clear();
+        self.pending_added.clear();
+    }
+}
+
+impl ConsumeHunk for SideBySideCollector {
+    type Out = Vec<SideBySideLine>;
+
+    fn consume_hunk(
+        &mut self,
+        header: HunkHeader,
+        entries: &[(DiffLineKind, &[u8])],
+    ) -> std::io::Result<()> {
+        self.flush_pending();
+        self.current_old_lineno = header.before_hunk_start;
+        self.current_new_lineno = header.after_hunk_start;
+
+        for (kind, content) in entries {
+            let content_str = String::from_utf8_lossy(content).to_string();
+
+            match kind {
+                DiffLineKind::Context => {
+                    self.flush_pending();
+                    self.lines.push(SideBySideLine {
+                        left_line_no: Some(self.current_old_lineno),
+                        right_line_no: Some(self.current_new_lineno),
+                        left_content: content_str.clone(),
+                        right_content: content_str,
+                        change_type: SideBySideChangeType::Unchanged,
+                    });
+                    self.current_old_lineno += 1;
+                    self.current_new_lineno += 1;
+                }
+                DiffLineKind::Add => {
+                    self.pending_added
+                        .push((self.current_new_lineno, content_str));
+                    self.current_new_lineno += 1;
+                }
+                DiffLineKind::Remove => {
+                    self.pending_removed
+                        .push((self.current_old_lineno, content_str));
+                    self.current_old_lineno += 1;
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn finish(mut self) -> Vec<SideBySideLine> {
+        self.flush_pending();
+        self.lines
+    }
+}
diff --git a/lib/git/cmd/diff/diff_stats.rs b/lib/git/cmd/diff/diff_stats.rs
new file mode 100644
index 0000000..cd2f42f
--- /dev/null
+++ b/lib/git/cmd/diff/diff_stats.rs
@@ -0,0 +1,104 @@
+use gix::bstr::ByteSlice;
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        diff::{
+            DiffOptions, DiffStats,
+            diff_tree_to_tree::{matches_pathspec, peel_to_tree},
+        },
+        oid::ObjectId,
+    },
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn diff_stats(
+        &self,
+        old_commit: ObjectId,
+        new_commit: ObjectId,
+        opts: Option<DiffOptions>,
+    ) -> GitResult<DiffStats> {
+        let repo = self.gix_repo()?;
+        let options = opts.unwrap_or_default();
+
+        let old_tree_obj = peel_to_tree(&repo, old_commit)?;
+        let new_tree_obj = peel_to_tree(&repo, new_commit)?;
+        let mut platform = old_tree_obj
+            .changes()
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+        platform.options(|opts| {
+            opts.track_rewrites(None);
+        });
+
+        let gix_stats = platform
+            .stats(&new_tree_obj)
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+        if options.pathspec.is_empty() {
+            Ok(DiffStats {
+                files_changed: gix_stats.files_changed as usize,
+                insertions: gix_stats.lines_added as usize,
+                deletions: gix_stats.lines_removed as usize,
+            })
+        } else {
+            let changes = repo
+                .diff_tree_to_tree(&old_tree_obj, &new_tree_obj, None)
+                .map_err(|e| GitError::Gix(e.to_string()))?;
+
+            let mut resource_cache =
+                repo.diff_resource_cache_for_tree_diff()
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+
+            let mut stats = DiffStats {
+                files_changed: 0,
+                insertions: 0,
+                deletions: 0,
+            };
+
+            for change in &changes {
+                let location = change.location().to_str().unwrap_or("");
+                if !matches_pathspec(&options.pathspec, location) {
+                    continue;
+                }
+
+                // Skip directories — only diff blobs
+                if change.entry_mode().is_tree() {
+                    stats.files_changed += 1;
+                    continue;
+                }
+
+                resource_cache
+                    .set_resource_by_change(change.to_ref(), &repo.objects)
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+
+                {
+                    use gix::diff::blob::platform::prepare_diff::Operation;
+
+                    let prep = resource_cache
+                        .prepare_diff()
+                        .map_err(|e| GitError::Gix(e.to_string()))?;
+
+                    if let Operation::InternalDiff { algorithm } =
+                        prep.operation
+                    {
+                        let input = prep.interned_input();
+                        let diff = gix::diff::blob::diff_with_slider_heuristics(
+                            algorithm, &input,
+                        );
+                        stats.files_changed += 1;
+                        stats.insertions += diff.count_additions() as usize;
+                        stats.deletions += diff.count_removals() as usize;
+                    } else if let Operation::SourceOrDestinationIsBinary =
+                        prep.operation
+                    {
+                        stats.files_changed += 1;
+                    }
+                }
+
+                resource_cache.clear_resource_cache_keep_allocation();
+            }
+
+            Ok(stats)
+        }
+    }
+}
diff --git a/lib/git/cmd/diff/diff_tree_to_tree.rs b/lib/git/cmd/diff/diff_tree_to_tree.rs
new file mode 100644
index 0000000..cf90878
--- /dev/null
+++ b/lib/git/cmd/diff/diff_tree_to_tree.rs
@@ -0,0 +1,362 @@
+use gix::{
+    bstr::ByteSlice,
+    diff::blob::unified_diff::{
+        ConsumeHunk, ContextSize, DiffLineKind, HunkHeader,
+    },
+};
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        diff::{
+            DiffDelta, DiffDeltaStatus, DiffFile, DiffHunk, DiffLine,
+            DiffOptions, DiffResult, DiffStats,
+        },
+        oid::ObjectId,
+    },
+    errors::{GitError, GitResult},
+};
+pub fn peel_to_tree(
+    repo: &gix::Repository,
+    oid: ObjectId,
+) -> GitResult<gix::Tree<'_>> {
+    let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+    if let Ok(tree) = repo.find_tree(gix_id) {
+        Ok(tree)
+    } else {
+        let commit = repo
+            .find_commit(gix_id)
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+        let tree_id = commit
+            .tree_id()
+            .map_err(|e| GitError::Gix(e.to_string()))?
+            .detach();
+        repo.find_tree(tree_id)
+            .map_err(|e| GitError::Gix(e.to_string()))
+    }
+}
+pub fn matches_pathspec(pathspec: &[String], path: &str) -> bool {
+    if pathspec.is_empty() {
+        return true;
+    }
+    pathspec
+        .iter()
+        .any(|spec| path == spec || path.starts_with(spec))
+}
+pub fn change_to_delta(
+    change: &gix::diff::tree_with_rewrites::Change,
+) -> DiffDelta {
+    use gix::diff::tree_with_rewrites::Change;
+
+    match change {
+        Change::Addition { location, id, .. } => {
+            let path = location.to_str().unwrap_or("").to_string();
+            DiffDelta {
+                status: DiffDeltaStatus::Added,
+                old_file: DiffFile {
+                    oid: None,
+                    path: Some(path.clone()),
+                    size: 0,
+                    is_binary: false,
+                },
+                new_file: DiffFile {
+                    oid: oid_to_option(id),
+                    path: Some(path),
+                    size: 0,
+                    is_binary: false,
+                },
+                nfiles: 1,
+                hunks: Vec::new(),
+                lines: Vec::new(),
+            }
+        }
+        Change::Deletion { location, id, .. } => {
+            let path = location.to_str().unwrap_or("").to_string();
+            DiffDelta {
+                status: DiffDeltaStatus::Deleted,
+                old_file: DiffFile {
+                    oid: oid_to_option(id),
+                    path: Some(path.clone()),
+                    size: 0,
+                    is_binary: false,
+                },
+                new_file: DiffFile {
+                    oid: None,
+                    path: Some(path),
+                    size: 0,
+                    is_binary: false,
+                },
+                nfiles: 1,
+                hunks: Vec::new(),
+                lines: Vec::new(),
+            }
+        }
+        Change::Modification {
+            location,
+            previous_entry_mode,
+            previous_id,
+            entry_mode,
+            id,
+        } => {
+            let path = location.to_str().unwrap_or("").to_string();
+            let status = if previous_entry_mode.kind() != entry_mode.kind() {
+                DiffDeltaStatus::Typechange
+            } else {
+                DiffDeltaStatus::Modified
+            };
+            DiffDelta {
+                status,
+                old_file: DiffFile {
+                    oid: oid_to_option(previous_id),
+                    path: Some(path.clone()),
+                    size: 0,
+                    is_binary: false,
+                },
+                new_file: DiffFile {
+                    oid: oid_to_option(id),
+                    path: Some(path),
+                    size: 0,
+                    is_binary: false,
+                },
+                nfiles: 1,
+                hunks: Vec::new(),
+                lines: Vec::new(),
+            }
+        }
+        Change::Rewrite {
+            source_location,
+            source_id,
+            location,
+            id,
+            copy,
+            ..
+        } => {
+            let old_path = source_location.to_str().unwrap_or("").to_string();
+            let new_path = location.to_str().unwrap_or("").to_string();
+            DiffDelta {
+                status: if *copy {
+                    DiffDeltaStatus::Copied
+                } else {
+                    DiffDeltaStatus::Renamed
+                },
+                old_file: DiffFile {
+                    oid: oid_to_option(source_id),
+                    path: Some(old_path),
+                    size: 0,
+                    is_binary: false,
+                },
+                new_file: DiffFile {
+                    oid: oid_to_option(id),
+                    path: Some(new_path),
+                    size: 0,
+                    is_binary: false,
+                },
+                nfiles: 2,
+                hunks: Vec::new(),
+                lines: Vec::new(),
+            }
+        }
+    }
+}
+
+pub fn oid_to_option(id: &gix::hash::oid) -> Option<ObjectId> {
+    if id.is_null() {
+        None
+    } else {
+        Some(ObjectId::new(id.to_hex().to_string()))
+    }
+}
+pub struct HunkCollector {
+    hunks: Vec<DiffHunk>,
+    lines: Vec<DiffLine>,
+    current_old_lineno: u32,
+    current_new_lineno: u32,
+}
+
+impl HunkCollector {
+    pub fn new() -> Self {
+        HunkCollector {
+            hunks: Vec::new(),
+            lines: Vec::new(),
+            current_old_lineno: 0,
+            current_new_lineno: 0,
+        }
+    }
+}
+
+impl ConsumeHunk for HunkCollector {
+    type Out = (Vec<DiffHunk>, Vec<DiffLine>);
+
+    fn consume_hunk(
+        &mut self,
+        header: HunkHeader,
+        entries: &[(DiffLineKind, &[u8])],
+    ) -> std::io::Result<()> {
+        self.current_old_lineno = header.before_hunk_start;
+        self.current_new_lineno = header.after_hunk_start;
+
+        self.hunks.push(DiffHunk {
+            old_start: header.before_hunk_start,
+            old_lines: header.before_hunk_len,
+            new_start: header.after_hunk_start,
+            new_lines: header.after_hunk_len,
+            header: format!(
+                "@@ -{},{} +{},{} @@",
+                header.before_hunk_start,
+                header.before_hunk_len,
+                header.after_hunk_start,
+                header.after_hunk_len
+            ),
+        });
+
+        for (kind, content) in entries {
+            let origin = kind.to_prefix();
+            let content_str = String::from_utf8_lossy(content).to_string();
+
+            let (old_lineno, new_lineno) = match kind {
+                DiffLineKind::Context => {
+                    let old = Some(self.current_old_lineno);
+                    let new = Some(self.current_new_lineno);
+                    self.current_old_lineno += 1;
+                    self.current_new_lineno += 1;
+                    (old, new)
+                }
+                DiffLineKind::Add => {
+                    let new = Some(self.current_new_lineno);
+                    self.current_new_lineno += 1;
+                    (None, new)
+                }
+                DiffLineKind::Remove => {
+                    let old = self.current_old_lineno;
+                    self.current_old_lineno += 1;
+                    (Some(old), None)
+                }
+            };
+
+            self.lines.push(DiffLine {
+                content: content_str,
+                origin,
+                old_lineno,
+                new_lineno,
+                num_lines: 1,
+                content_offset: -1,
+            });
+        }
+
+        Ok(())
+    }
+
+    fn finish(self) -> (Vec<DiffHunk>, Vec<DiffLine>) {
+        (self.hunks, self.lines)
+    }
+}
+
+impl GitBare {
+    pub fn diff_tree_to_tree(
+        &self,
+        old_tree: ObjectId,
+        new_tree: ObjectId,
+        opts: Option<DiffOptions>,
+    ) -> GitResult<DiffResult> {
+        let repo = self.gix_repo()?;
+        let options = opts.unwrap_or_default();
+
+        let old_tree_obj = peel_to_tree(&repo, old_tree)?;
+        let new_tree_obj = peel_to_tree(&repo, new_tree)?;
+
+        let mut diff_opts = gix::diff::Options::default();
+        diff_opts.track_path();
+
+        let changes = repo
+            .diff_tree_to_tree(&old_tree_obj, &new_tree_obj, Some(diff_opts))
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut resource_cache = repo
+            .diff_resource_cache_for_tree_diff()
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+
+        let mut deltas = Vec::new();
+        let mut stats = DiffStats {
+            files_changed: 0,
+            insertions: 0,
+            deletions: 0,
+        };
+
+        for change in &changes {
+            let location = change.location().to_str().unwrap_or("");
+            if !matches_pathspec(&options.pathspec, location) {
+                continue;
+            }
+
+            let mut delta = change_to_delta(change);
+
+            // Skip directories — only diff blobs
+            if change.entry_mode().is_tree() {
+                stats.files_changed += 1;
+                resource_cache.clear_resource_cache_keep_allocation();
+                deltas.push(delta);
+                continue;
+            }
+
+            resource_cache
+                .set_resource_by_change(change.to_ref(), &repo.objects)
+                .map_err(|e| GitError::Gix(e.to_string()))?;
+
+            let is_binary = {
+                use gix::diff::blob::platform::prepare_diff::Operation;
+
+                let prep = resource_cache
+                    .prepare_diff()
+                    .map_err(|e| GitError::Gix(e.to_string()))?;
+
+                match prep.operation {
+                    Operation::InternalDiff { algorithm } => {
+                        let input = prep.interned_input();
+                        let diff = gix::diff::blob::diff_with_slider_heuristics(
+                            algorithm, &input,
+                        );
+
+                        stats.files_changed += 1;
+                        stats.insertions += diff.count_additions() as usize;
+                        stats.deletions += diff.count_removals() as usize;
+
+                        if options.context_lines > 0 {
+                            let ctx = ContextSize::symmetrical(
+                                options.context_lines.max(3),
+                            );
+                            let collector = HunkCollector::new();
+                            let unified = gix::diff::blob::UnifiedDiff::new(
+                                &diff, &input, collector, ctx,
+                            );
+                            let (hunks, lines) = unified
+                                .consume()
+                                .map_err(|e| GitError::Gix(e.to_string()))?;
+                            delta.hunks = hunks;
+                            delta.lines = lines;
+                        }
+
+                        false
+                    }
+                    Operation::SourceOrDestinationIsBinary => {
+                        stats.files_changed += 1;
+                        true
+                    }
+                    Operation::ExternalCommand { .. } => {
+                        stats.files_changed += 1;
+                        false
+                    }
+                }
+            };
+
+            if is_binary {
+                delta.old_file.is_binary = true;
+                delta.new_file.is_binary = true;
+            }
+
+            resource_cache.clear_resource_cache_keep_allocation();
+            deltas.push(delta);
+        }
+
+        Ok(DiffResult { stats, deltas })
+    }
+}
diff --git a/lib/git/cmd/diff/mod.rs b/lib/git/cmd/diff/mod.rs
new file mode 100644
index 0000000..8090352
--- /dev/null
+++ b/lib/git/cmd/diff/mod.rs
@@ -0,0 +1,113 @@
+use serde::{Deserialize, Serialize};
+
+use crate::cmd::oid::ObjectId;
+
+pub mod diff_index_to_tree;
+pub mod diff_patch;
+pub mod diff_stats;
+pub mod diff_tree_to_tree;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum DiffDeltaStatus {
+    Unmodified,
+    Added,
+    Deleted,
+    Modified,
+    Renamed,
+    Copied,
+    Typechange,
+    Conflicted,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiffFile {
+    pub oid: Option<ObjectId>,
+    pub path: Option<String>,
+    pub size: u64,
+    pub is_binary: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiffHunk {
+    pub old_start: u32,
+    pub old_lines: u32,
+    pub new_start: u32,
+    pub new_lines: u32,
+    pub header: String,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiffDelta {
+    pub status: DiffDeltaStatus,
+    pub old_file: DiffFile,
+    pub new_file: DiffFile,
+    pub nfiles: u16,
+    pub hunks: Vec<DiffHunk>,
+    pub lines: Vec<DiffLine>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiffLine {
+    pub content: String,
+    pub origin: char,
+    pub old_lineno: Option<u32>,
+    pub new_lineno: Option<u32>,
+    pub num_lines: u32,
+    pub content_offset: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiffStats {
+    pub files_changed: usize,
+    pub insertions: usize,
+    pub deletions: usize,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiffResult {
+    pub stats: DiffStats,
+    pub deltas: Vec<DiffDelta>,
+}
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum SideBySideChangeType {
+    Unchanged,
+    Added,
+    Removed,
+    Modified,
+    Empty,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SideBySideLine {
+    pub left_line_no: Option<u32>,
+    pub right_line_no: Option<u32>,
+    pub left_content: String,
+    pub right_content: String,
+    pub change_type: SideBySideChangeType,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SideBySideFile {
+    pub path: String,
+    pub additions: usize,
+    pub deletions: usize,
+    pub is_binary: bool,
+    pub is_rename: bool,
+    pub lines: Vec<SideBySideLine>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SideBySideDiffResult {
+    pub files: Vec<SideBySideFile>,
+    pub total_additions: usize,
+    pub total_deletions: usize,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct DiffOptions {
+    pub context_lines: u32,
+    pub pathspec: Vec<String>,
+    pub ignore_whitespace: bool,
+    pub force_text: bool,
+    pub reverse: bool,
+}
diff --git a/lib/git/cmd/fork.rs b/lib/git/cmd/fork.rs
new file mode 100644
index 0000000..97c7273
--- /dev/null
+++ b/lib/git/cmd/fork.rs
@@ -0,0 +1,111 @@
+use std::path::PathBuf;
+
+use crate::{
+    bare::GitBare,
+    errors::{GitError, GitResult},
+};
+
+pub struct ForkRepoParams {
+    pub namespace: String,
+    pub repo_name: String,
+    pub default_branch: String,
+    pub description: Option<String>,
+    pub enable_lfs: bool,
+}
+
+impl ForkRepoParams {
+    pub async fn fork_bare(
+        storage_root: String,
+        source_storage_path: String,
+        params: ForkRepoParams,
+    ) -> GitResult<String> {
+        let target_dir = PathBuf::from(&storage_root)
+            .join("repo")
+            .join(&params.namespace)
+            .join(&params.repo_name);
+
+        if target_dir.exists() {
+            return Err(GitError::Internal(format!(
+                "repository directory already exists: {}",
+                target_dir.display()
+            )));
+        }
+
+        let source_dir = PathBuf::from(&source_storage_path);
+        if !source_dir.exists() {
+            return Err(GitError::Internal(format!(
+                "source repository does not exist: {}",
+                source_dir.display()
+            )));
+        }
+        let output = duct::cmd(
+            "git",
+            &[
+                "clone",
+                "--bare",
+                source_dir.to_string_lossy().as_ref(),
+                target_dir.to_string_lossy().as_ref(),
+            ],
+        )
+        .stdout_capture()
+        .stderr_capture()
+        .env("GIT_CONFIG_NOSYSTEM", "1")
+        .env("GIT_TERMINAL_PROMPT", "0")
+        .unchecked()
+        .run()?;
+
+        if !output.status.success() {
+            std::fs::remove_dir_all(&target_dir).ok();
+            return Err(GitError::CommandFailed {
+                status_code: output.status.code(),
+                stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+            });
+        }
+
+        let bare = GitBare {
+            bare_dir: target_dir.clone(),
+        };
+        let symref_output = bare.git_command_trusted(vec![
+            "symbolic-ref".to_string(),
+            "HEAD".to_string(),
+            format!("refs/heads/{}", params.default_branch),
+        ])?;
+        if !symref_output.success {
+            return Err(GitError::CommandFailed {
+                status_code: symref_output.status_code,
+                stderr: symref_output.stderr_lossy(),
+            });
+        }
+        let remote_output = bare.git_command_trusted(vec![
+            "remote".to_string(),
+            "add".to_string(),
+            "upstream".to_string(),
+            source_dir.to_string_lossy().to_string(),
+        ])?;
+        if !remote_output.success {
+            tracing::warn!(
+                "failed to add upstream remote: {}",
+                remote_output.stderr_lossy()
+            );
+        }
+        if let Some(desc) = &params.description {
+            let desc_path = target_dir.join("description");
+            std::fs::write(&desc_path, desc)?;
+        }
+        if params.enable_lfs {
+            let gitattributes_path = target_dir.join("info").join("attributes");
+            if let Some(parent) = gitattributes_path.parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            let lfs_attributes = "*.psd filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.zip filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.tar filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.gz filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.mp4 filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.mov filter=lfs diff=lfs merge=lfs -text\n";
+            std::fs::write(&gitattributes_path, lfs_attributes)?;
+        }
+
+        Ok(target_dir.to_string_lossy().to_string())
+    }
+}
diff --git a/lib/git/cmd/init.rs b/lib/git/cmd/init.rs
new file mode 100644
index 0000000..7341b3e
--- /dev/null
+++ b/lib/git/cmd/init.rs
@@ -0,0 +1,235 @@
+use std::path::PathBuf;
+
+use crate::{
+    bare::GitBare,
+    errors::{GitError, GitResult},
+};
+
+pub struct InitRepositoriesParams {
+    pub namespace: String,
+    pub repo_name: String,
+    pub default_branch: String,
+    pub description: Option<String>,
+    pub initialize_with_readme: bool,
+    pub enable_lfs: bool,
+}
+
+pub struct CloneRepoParams {
+    pub namespace: String,
+    pub repo_name: String,
+    pub source_url: String,
+}
+
+impl CloneRepoParams {
+    pub async fn clone_bare(
+        storage_root: String,
+        params: CloneRepoParams,
+    ) -> GitResult<String> {
+        let repo_dir = PathBuf::from(&storage_root)
+            .join("repo")
+            .join(&params.namespace)
+            .join(&params.repo_name);
+
+        if repo_dir.exists() {
+            return Err(GitError::Internal(format!(
+                "repository directory already exists: {}",
+                repo_dir.display()
+            )));
+        }
+
+        if let Some(parent) = repo_dir.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+
+        // Clone as bare repo from source URL
+        let output = duct::cmd(
+            "git",
+            &[
+                "clone",
+                "--bare",
+                &params.source_url,
+                repo_dir.to_string_lossy().as_ref(),
+            ],
+        )
+        .stdout_capture()
+        .stderr_capture()
+        .env("GIT_CONFIG_NOSYSTEM", "1")
+        .env("GIT_TERMINAL_PROMPT", "0")
+        .unchecked()
+        .run()?;
+
+        if !output.status.success() {
+            std::fs::remove_dir_all(&repo_dir).ok();
+            return Err(GitError::CommandFailed {
+                status_code: output.status.code(),
+                stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+            });
+        }
+
+        Ok(repo_dir.to_string_lossy().to_string())
+    }
+}
+
+impl InitRepositoriesParams {
+    pub async fn init_bare(
+        basic_path: String,
+        params: InitRepositoriesParams,
+    ) -> GitResult<String> {
+        let repo_dir = PathBuf::from(&basic_path)
+            .join("repo")
+            .join(&params.namespace)
+            .join(&params.repo_name);
+
+        if repo_dir.exists() {
+            return Err(GitError::Internal(format!(
+                "repository directory already exists: {}",
+                repo_dir.display()
+            )));
+        }
+
+        std::fs::create_dir_all(&repo_dir)?;
+        let output = duct::cmd("git", &["init", "--bare"])
+            .dir(&repo_dir)
+            .stdout_capture()
+            .stderr_capture()
+            .env("GIT_CONFIG_NOSYSTEM", "1")
+            .env("GIT_TERMINAL_PROMPT", "0")
+            .unchecked()
+            .run()?;
+
+        if !output.status.success() {
+            std::fs::remove_dir_all(&repo_dir).ok();
+            return Err(GitError::CommandFailed {
+                status_code: output.status.code(),
+                stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+            });
+        }
+
+        let bare = GitBare {
+            bare_dir: repo_dir.clone(),
+        };
+        let symref_output = bare.git_command_trusted(vec![
+            "symbolic-ref".to_string(),
+            "HEAD".to_string(),
+            format!("refs/heads/{}", params.default_branch),
+        ])?;
+        if !symref_output.success {
+            return Err(GitError::CommandFailed {
+                status_code: symref_output.status_code,
+                stderr: symref_output.stderr_lossy(),
+            });
+        }
+        if let Some(desc) = &params.description {
+            let desc_path = repo_dir.join("description");
+            std::fs::write(&desc_path, desc)?;
+        }
+        if params.enable_lfs {
+            let gitattributes_path = repo_dir.join("info").join("attributes");
+            if let Some(parent) = gitattributes_path.parent() {
+                std::fs::create_dir_all(parent)?;
+            }
+            let lfs_attributes = "*.psd filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.zip filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.tar filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.gz filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.mp4 filter=lfs diff=lfs merge=lfs -text\n\
+                                  *.mov filter=lfs diff=lfs merge=lfs -text\n";
+            std::fs::write(&gitattributes_path, lfs_attributes)?;
+        }
+        if params.initialize_with_readme {
+            init_initial_commit(&bare, &params)?;
+        }
+
+        Ok(repo_dir.to_string_lossy().to_string())
+    }
+}
+
+fn duct_output_to_error(output: &std::process::Output) -> GitError {
+    GitError::CommandFailed {
+        status_code: output.status.code(),
+        stderr: String::from_utf8_lossy(&output.stderr).into_owned(),
+    }
+}
+
+fn init_initial_commit(
+    bare: &GitBare,
+    params: &InitRepositoriesParams,
+) -> GitResult<()> {
+    let tmp_dir = bare.bare_dir.with_extension("tmp-init");
+    let clone_output = duct::cmd(
+        "git",
+        &[
+            "clone",
+            bare.bare_dir.to_string_lossy().as_ref(),
+            tmp_dir.to_string_lossy().as_ref(),
+        ],
+    )
+    .stdout_capture()
+    .stderr_capture()
+    .unchecked()
+    .run()?;
+
+    if !clone_output.status.success() {
+        return Err(duct_output_to_error(&clone_output));
+    }
+    let checkout_output =
+        duct::cmd("git", &["checkout", "-b", &params.default_branch])
+            .dir(&tmp_dir)
+            .stdout_capture()
+            .stderr_capture()
+            .unchecked()
+            .run()?;
+
+    if !checkout_output.status.success() {
+        std::fs::remove_dir_all(&tmp_dir).ok();
+        return Err(duct_output_to_error(&checkout_output));
+    }
+    let readme_content = format!(
+        "# {}\n\n{}",
+        params.repo_name,
+        params.description.as_deref().unwrap_or("")
+    );
+    let readme_path = tmp_dir.join("README.md");
+    std::fs::write(&readme_path, readme_content)?;
+    let add_output = duct::cmd("git", &["add", "README.md"])
+        .dir(&tmp_dir)
+        .stdout_capture()
+        .stderr_capture()
+        .unchecked()
+        .run()?;
+
+    if !add_output.status.success() {
+        std::fs::remove_dir_all(&tmp_dir).ok();
+        return Err(duct_output_to_error(&add_output));
+    }
+    let commit_output = duct::cmd("git", &["commit", "-m", "Initial commit"])
+        .dir(&tmp_dir)
+        .stdout_capture()
+        .stderr_capture()
+        .env("GIT_CONFIG_NOSYSTEM", "1")
+        .env("GIT_COMMITTER_NAME", "panda")
+        .env("GIT_COMMITTER_EMAIL", "panda@gitdata.ai")
+        .env("GIT_AUTHOR_NAME", "panda")
+        .env("GIT_AUTHOR_EMAIL", "panda@gitdata.ai")
+        .unchecked()
+        .run()?;
+
+    if !commit_output.status.success() {
+        std::fs::remove_dir_all(&tmp_dir).ok();
+        return Err(duct_output_to_error(&commit_output));
+    }
+    let push_output =
+        duct::cmd("git", &["push", "origin", &params.default_branch])
+            .dir(&tmp_dir)
+            .stdout_capture()
+            .stderr_capture()
+            .unchecked()
+            .run()?;
+    std::fs::remove_dir_all(&tmp_dir).ok();
+
+    if !push_output.status.success() {
+        return Err(duct_output_to_error(&push_output));
+    }
+
+    Ok(())
+}
diff --git a/lib/git/cmd/merge/merge_abort.rs b/lib/git/cmd/merge/merge_abort.rs
new file mode 100644
index 0000000..de0758d
--- /dev/null
+++ b/lib/git/cmd/merge/merge_abort.rs
@@ -0,0 +1,13 @@
+use crate::{bare::GitBare, errors::GitResult};
+
+impl GitBare {
+    pub fn merge_abort(&self) -> GitResult<()> {
+        self.git_command_trusted_stdout(vec![
+            "update-ref".to_string(),
+            "-d".to_string(),
+            "MERGE_HEAD".to_string(),
+        ])?;
+
+        Ok(())
+    }
+}
diff --git a/lib/git/cmd/merge/merge_analysis.rs b/lib/git/cmd/merge/merge_analysis.rs
new file mode 100644
index 0000000..d0ca1d4
--- /dev/null
+++ b/lib/git/cmd/merge/merge_analysis.rs
@@ -0,0 +1,76 @@
+use crate::{
+    bare::GitBare,
+    cmd::{
+        merge::{MergeAnalysisResult, MergePreferenceResult},
+        oid::ObjectId,
+    },
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn merge_analysis(
+        &self,
+        their_commit: ObjectId,
+    ) -> GitResult<(MergeAnalysisResult, MergePreferenceResult)> {
+        let repo = self.gix_repo()?;
+        let their_gix_id: gix::hash::ObjectId = (&their_commit).try_into()?;
+        let head_id = repo.head_id()?;
+        let head_gix_id = head_id.detach();
+        let is_up_to_date = repo
+            .merge_base(their_gix_id, head_gix_id)
+            .ok()
+            .is_some_and(|base| base.detach() == their_gix_id);
+
+        if is_up_to_date {
+            return Ok((
+                MergeAnalysisResult {
+                    is_none: false,
+                    is_normal: false,
+                    is_up_to_date: true,
+                    is_fast_forward: false,
+                    is_unborn: false,
+                },
+                MergePreferenceResult {
+                    is_none: false,
+                    is_no_fast_forward: false,
+                    is_fastforward_only: false,
+                },
+            ));
+        }
+        let is_fast_forward = repo
+            .merge_base(head_gix_id, their_gix_id)
+            .ok()
+            .is_some_and(|base| base.detach() == head_gix_id);
+
+        if is_fast_forward {
+            return Ok((
+                MergeAnalysisResult {
+                    is_none: false,
+                    is_normal: false,
+                    is_up_to_date: false,
+                    is_fast_forward: true,
+                    is_unborn: false,
+                },
+                MergePreferenceResult {
+                    is_none: false,
+                    is_no_fast_forward: false,
+                    is_fastforward_only: false,
+                },
+            ));
+        }
+        Ok((
+            MergeAnalysisResult {
+                is_none: false,
+                is_normal: true,
+                is_up_to_date: false,
+                is_fast_forward: false,
+                is_unborn: false,
+            },
+            MergePreferenceResult {
+                is_none: false,
+                is_no_fast_forward: false,
+                is_fastforward_only: false,
+            },
+        ))
+    }
+}
diff --git a/lib/git/cmd/merge/merge_analysis_for_ref.rs b/lib/git/cmd/merge/merge_analysis_for_ref.rs
new file mode 100644
index 0000000..77f28ae
--- /dev/null
+++ b/lib/git/cmd/merge/merge_analysis_for_ref.rs
@@ -0,0 +1,81 @@
+use crate::{
+    bare::GitBare,
+    cmd::merge::{MergeAnalysisResult, MergePreferenceResult},
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn merge_analysis_for_ref(
+        &self,
+        ref_name: String,
+    ) -> GitResult<(MergeAnalysisResult, MergePreferenceResult)> {
+        let repo = self.gix_repo()?;
+        let their_id =
+            repo.rev_parse_single(ref_name.as_str()).map_err(|_| {
+                GitError::RefNotFound(format!(
+                    "reference '{}' could not be resolved",
+                    ref_name
+                ))
+            })?;
+        let their_gix_id = their_id.detach();
+
+        let head_id = repo.head_id()?;
+        let head_gix_id = head_id.detach();
+        let is_up_to_date = repo
+            .merge_base(their_gix_id, head_gix_id)
+            .ok()
+            .is_some_and(|base| base.detach() == their_gix_id);
+
+        if is_up_to_date {
+            return Ok((
+                MergeAnalysisResult {
+                    is_none: false,
+                    is_normal: false,
+                    is_up_to_date: true,
+                    is_fast_forward: false,
+                    is_unborn: false,
+                },
+                MergePreferenceResult {
+                    is_none: false,
+                    is_no_fast_forward: false,
+                    is_fastforward_only: false,
+                },
+            ));
+        }
+        let is_fast_forward = repo
+            .merge_base(head_gix_id, their_gix_id)
+            .ok()
+            .is_some_and(|base| base.detach() == head_gix_id);
+
+        if is_fast_forward {
+            return Ok((
+                MergeAnalysisResult {
+                    is_none: false,
+                    is_normal: false,
+                    is_up_to_date: false,
+                    is_fast_forward: true,
+                    is_unborn: false,
+                },
+                MergePreferenceResult {
+                    is_none: false,
+                    is_no_fast_forward: false,
+                    is_fastforward_only: false,
+                },
+            ));
+        }
+        Ok((
+            MergeAnalysisResult {
+                is_none: false,
+                is_normal: true,
+                is_up_to_date: false,
+                is_fast_forward: false,
+                is_unborn: false,
+            },
+            MergePreferenceResult {
+                is_none: false,
+                is_no_fast_forward: false,
+                is_fastforward_only: false,
+            },
+        ))
+    }
+}
diff --git a/lib/git/cmd/merge/merge_base.rs b/lib/git/cmd/merge/merge_base.rs
new file mode 100644
index 0000000..e06c82c
--- /dev/null
+++ b/lib/git/cmd/merge/merge_base.rs
@@ -0,0 +1,26 @@
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn merge_base(
+        &self,
+        one: ObjectId,
+        two: ObjectId,
+    ) -> GitResult<ObjectId> {
+        let repo = self.gix_repo()?;
+        let gix_one: gix::hash::ObjectId = (&one).try_into()?;
+        let gix_two: gix::hash::ObjectId = (&two).try_into()?;
+
+        let base = repo.merge_base(gix_one, gix_two).map_err(|_| {
+            GitError::ObjectNotFound(format!(
+                "no merge base found between {} and {}",
+                one, two
+            ))
+        })?;
+
+        Ok(ObjectId::new(base.detach().to_hex().to_string()))
+    }
+}
diff --git a/lib/git/cmd/merge/merge_base_many.rs b/lib/git/cmd/merge/merge_base_many.rs
new file mode 100644
index 0000000..85f789b
--- /dev/null
+++ b/lib/git/cmd/merge/merge_base_many.rs
@@ -0,0 +1,36 @@
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn merge_base_many(
+        &self,
+        commits: Vec<ObjectId>,
+    ) -> GitResult<ObjectId> {
+        if commits.len() < 2 {
+            return Err(GitError::ParseError(
+                "merge_base_many requires at least 2 commits".to_string(),
+            ));
+        }
+
+        let repo = self.gix_repo()?;
+        let gix_commits: Vec<gix::hash::ObjectId> = commits
+            .iter()
+            .map(|id| id.try_into())
+            .collect::<Result<Vec<_>, _>>()?;
+
+        let first = gix_commits[0];
+        let others = &gix_commits[1..];
+
+        let bases = repo.merge_bases_many(first, others)?;
+        let base = bases.first().ok_or_else(|| {
+            GitError::ObjectNotFound(
+                "no common merge base found for the given commits".to_string(),
+            )
+        })?;
+
+        Ok(ObjectId::new(base.detach().to_hex().to_string()))
+    }
+}
diff --git a/lib/git/cmd/merge/merge_base_octopus.rs b/lib/git/cmd/merge/merge_base_octopus.rs
new file mode 100644
index 0000000..5debeef
--- /dev/null
+++ b/lib/git/cmd/merge/merge_base_octopus.rs
@@ -0,0 +1,32 @@
+use crate::{
+    bare::GitBare,
+    cmd::oid::ObjectId,
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn merge_base_octopus(
+        &self,
+        commits: Vec<ObjectId>,
+    ) -> GitResult<ObjectId> {
+        if commits.len() < 2 {
+            return Err(GitError::ParseError(
+                "merge_base_octopus requires at least 2 commits".to_string(),
+            ));
+        }
+
+        let repo = self.gix_repo()?;
+        let gix_commits: Vec<gix::hash::ObjectId> = commits
+            .iter()
+            .map(|id| id.try_into())
+            .collect::<Result<Vec<_>, _>>()?;
+
+        let base = repo.merge_base_octopus(gix_commits).map_err(|_| {
+            GitError::ObjectNotFound(
+                "no octopus merge base found for the given commits".to_string(),
+            )
+        })?;
+
+        Ok(ObjectId::new(base.detach().to_hex().to_string()))
+    }
+}
diff --git a/lib/git/cmd/merge/merge_commit.rs b/lib/git/cmd/merge/merge_commit.rs
new file mode 100644
index 0000000..a814181
--- /dev/null
+++ b/lib/git/cmd/merge/merge_commit.rs
@@ -0,0 +1,127 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        commit::CommitSignature, merge::MergeOptions, oid::ObjectId,
+        parse::format_git_timestamp,
+    },
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct MergeCommitParams {
+    pub their_commit: ObjectId,
+    pub author: CommitSignature,
+    pub committer: CommitSignature,
+    pub message: String,
+    pub update_ref: Option<String>,
+    pub options: Option<MergeOptions>,
+}
+
+impl GitBare {
+    pub fn merge_commit(
+        &self,
+        params: MergeCommitParams,
+    ) -> GitResult<ObjectId> {
+        let repo = self.gix_repo()?;
+        let head_id =
+            repo.head_id().map_err(|e| GitError::Gix(e.to_string()))?;
+        let head_oid = ObjectId::new(head_id.detach().to_hex().to_string());
+        let mut merge_tree_args =
+            vec!["merge-tree".to_string(), "--write-tree".to_string()];
+        if let Some(opts) = &params.options {
+            if opts.find_renames {
+                merge_tree_args.push("--find-renames".to_string());
+                if opts.rename_threshold > 0 {
+                    merge_tree_args.push(format!(
+                        "--rename-threshold={}",
+                        opts.rename_threshold
+                    ));
+                }
+            }
+            if opts.fail_on_conflict {
+                merge_tree_args.push("--fail-on-conflict".to_string());
+            }
+        }
+        merge_tree_args.push(head_oid.as_str().to_string());
+        merge_tree_args.push(params.their_commit.as_str().to_string());
+
+        let merge_tree_output = self.git_command_stdout(merge_tree_args)?;
+        let tree_oid_str =
+            merge_tree_output.lines().next().unwrap_or("").trim();
+        if tree_oid_str.is_empty() {
+            return Err(GitError::CommandFailed {
+                status_code: None,
+                stderr: "merge-tree produced no output".to_string(),
+            });
+        }
+
+        let tree_oid = ObjectId::new(tree_oid_str);
+        let commit_tree_args = vec![
+            "commit-tree".to_string(),
+            tree_oid.as_str().to_string(),
+            "-p".to_string(),
+            head_oid.as_str().to_string(),
+            "-p".to_string(),
+            params.their_commit.as_str().to_string(),
+            "-F".to_string(),
+            "-".to_string(), // read message from stdin
+        ];
+
+        let author_timestamp = format_git_timestamp(
+            params.author.time_secs,
+            params.author.offset_minutes,
+        );
+        let committer_timestamp = format_git_timestamp(
+            params.committer.time_secs,
+            params.committer.offset_minutes,
+        );
+
+        let commit_output = self.git_command_with(
+            crate::cmd::command::GitCommandParams::new(commit_tree_args)
+                .with_stdin(params.message.as_bytes().to_vec())
+                .with_env(
+                    "GIT_AUTHOR_NAME".to_string(),
+                    params.author.name.clone(),
+                )
+                .with_env(
+                    "GIT_AUTHOR_EMAIL".to_string(),
+                    params.author.email.clone(),
+                )
+                .with_env("GIT_AUTHOR_DATE".to_string(), author_timestamp)
+                .with_env(
+                    "GIT_COMMITTER_NAME".to_string(),
+                    params.committer.name.clone(),
+                )
+                .with_env(
+                    "GIT_COMMITTER_EMAIL".to_string(),
+                    params.committer.email.clone(),
+                )
+                .with_env(
+                    "GIT_COMMITTER_DATE".to_string(),
+                    committer_timestamp,
+                ),
+        )?;
+
+        let stdout_str = commit_output.stdout_lossy();
+        let commit_oid_str = stdout_str.trim();
+        if commit_oid_str.is_empty() {
+            return Err(GitError::CommandFailed {
+                status_code: commit_output.status_code,
+                stderr: commit_output.stderr_lossy(),
+            });
+        }
+
+        let result_oid = ObjectId::new(commit_oid_str);
+        if let Some(ref_name) = &params.update_ref {
+            self.git_command_trusted_stdout(vec![
+                "update-ref".to_string(),
+                ref_name.clone(),
+                result_oid.as_str().to_string(),
+            ])?;
+        }
+
+        Ok(result_oid)
+    }
+}
diff --git a/lib/git/cmd/merge/merge_is_conflicted.rs b/lib/git/cmd/merge/merge_is_conflicted.rs
new file mode 100644
index 0000000..9dac48e
--- /dev/null
+++ b/lib/git/cmd/merge/merge_is_conflicted.rs
@@ -0,0 +1,8 @@
+use crate::{bare::GitBare, errors::GitResult};
+
+impl GitBare {
+    pub fn merge_is_conflicted(&self) -> GitResult<bool> {
+        let repo = self.gix_repo()?;
+        Ok(repo.try_find_reference("MERGE_HEAD")?.is_some())
+    }
+}
diff --git a/lib/git/cmd/merge/merge_tree.rs b/lib/git/cmd/merge/merge_tree.rs
new file mode 100644
index 0000000..fd7da4a
--- /dev/null
+++ b/lib/git/cmd/merge/merge_tree.rs
@@ -0,0 +1,76 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{merge::MergeOptions, oid::ObjectId},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct MergeTreeResult {
+    pub tree_id: ObjectId,
+    pub has_conflicts: bool,
+}
+
+impl GitBare {
+    pub fn merge_tree(
+        &self,
+        ours: ObjectId,
+        theirs: ObjectId,
+        options: Option<MergeOptions>,
+    ) -> GitResult<MergeTreeResult> {
+        let mut args =
+            vec!["merge-tree".to_string(), "--write-tree".to_string()];
+
+        if let Some(opts) = &options {
+            if opts.find_renames {
+                args.push("--find-renames".to_string());
+                if opts.rename_threshold > 0 {
+                    args.push(format!(
+                        "--rename-threshold={}",
+                        opts.rename_threshold
+                    ));
+                }
+            }
+            if opts.fail_on_conflict {
+                args.push("--fail-on-conflict".to_string());
+            }
+            if opts.no_recursive {
+                args.push("--no-recursive".to_string());
+            }
+            if opts.target_limit > 0 {
+                args.push(format!("--target-limit={}", opts.target_limit));
+            }
+        }
+
+        args.push(ours.as_str().to_string());
+        args.push(theirs.as_str().to_string());
+
+        let output = self.git_command_with(
+            crate::cmd::command::GitCommandParams::new(args).unchecked(),
+        )?;
+
+        let stdout = output.stdout_lossy();
+        let mut lines = stdout.lines();
+        let tree_oid_str = lines.next().unwrap_or("").trim();
+
+        if tree_oid_str.is_empty() {
+            if !output.success {
+                return Err(GitError::CommandFailed {
+                    status_code: output.status_code,
+                    stderr: output.stderr_lossy(),
+                });
+            }
+            return Err(GitError::ParseError(
+                "merge-tree produced no tree OID output".to_string(),
+            ));
+        }
+        let has_conflicts =
+            !output.success || lines.any(|l| !l.trim().is_empty());
+
+        Ok(MergeTreeResult {
+            tree_id: ObjectId::new(tree_oid_str),
+            has_conflicts,
+        })
+    }
+}
diff --git a/lib/git/cmd/merge/mergehead_list.rs b/lib/git/cmd/merge/mergehead_list.rs
new file mode 100644
index 0000000..8f0ff19
--- /dev/null
+++ b/lib/git/cmd/merge/mergehead_list.rs
@@ -0,0 +1,20 @@
+use crate::{bare::GitBare, cmd::oid::ObjectId, errors::GitResult};
+
+impl GitBare {
+    pub fn mergehead_list(&self) -> GitResult<Vec<ObjectId>> {
+        let merge_head_path = self.bare_dir.canonicalize()?.join("MERGE_HEAD");
+
+        if !merge_head_path.exists() {
+            return Ok(Vec::new());
+        }
+
+        let content = std::fs::read_to_string(&merge_head_path)?;
+        let oids: Vec<ObjectId> = content
+            .lines()
+            .filter(|line| !line.trim().is_empty())
+            .map(|line| ObjectId::new(line.trim()))
+            .collect();
+
+        Ok(oids)
+    }
+}
diff --git a/lib/git/cmd/merge/mod.rs b/lib/git/cmd/merge/mod.rs
new file mode 100644
index 0000000..c2e9c9d
--- /dev/null
+++ b/lib/git/cmd/merge/mod.rs
@@ -0,0 +1,43 @@
+use serde::{Deserialize, Serialize};
+
+pub mod merge_abort;
+pub mod merge_analysis;
+pub mod merge_analysis_for_ref;
+pub mod merge_base;
+pub mod merge_base_many;
+pub mod merge_base_octopus;
+pub mod merge_commit;
+pub mod merge_is_conflicted;
+pub mod merge_tree;
+pub mod mergehead_list;
+pub mod squash_commit;
+
+pub use merge_commit::MergeCommitParams;
+pub use merge_tree::MergeTreeResult;
+pub use squash_commit::SquashCommitParams;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MergeAnalysisResult {
+    pub is_none: bool,
+    pub is_normal: bool,
+    pub is_up_to_date: bool,
+    pub is_fast_forward: bool,
+    pub is_unborn: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MergePreferenceResult {
+    pub is_none: bool,
+    pub is_no_fast_forward: bool,
+    pub is_fastforward_only: bool,
+}
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct MergeOptions {
+    pub find_renames: bool,
+    pub fail_on_conflict: bool,
+    pub skip_reuc: bool,
+    pub no_recursive: bool,
+    pub rename_threshold: u32,
+    pub target_limit: u32,
+    pub recursion_limit: u32,
+}
diff --git a/lib/git/cmd/merge/squash_commit.rs b/lib/git/cmd/merge/squash_commit.rs
new file mode 100644
index 0000000..31e4079
--- /dev/null
+++ b/lib/git/cmd/merge/squash_commit.rs
@@ -0,0 +1,120 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{merge::MergeOptions, oid::ObjectId, parse::format_git_timestamp},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct SquashCommitParams {
+    pub their_commit: ObjectId,
+    pub options: Option<MergeOptions>,
+}
+
+impl GitBare {
+    pub fn squash_commit(
+        &self,
+        params: SquashCommitParams,
+    ) -> GitResult<ObjectId> {
+        let repo = self.gix_repo()?;
+        let head_id =
+            repo.head_id().map_err(|e| GitError::Gix(e.to_string()))?;
+        let head_oid = ObjectId::new(head_id.detach().to_hex().to_string());
+        let mut merge_tree_args =
+            vec!["merge-tree".to_string(), "--write-tree".to_string()];
+        if let Some(opts) = &params.options {
+            if opts.find_renames {
+                merge_tree_args.push("--find-renames".to_string());
+                if opts.rename_threshold > 0 {
+                    merge_tree_args.push(format!(
+                        "--rename-threshold={}",
+                        opts.rename_threshold
+                    ));
+                }
+            }
+            if opts.fail_on_conflict {
+                merge_tree_args.push("--fail-on-conflict".to_string());
+            }
+        }
+        merge_tree_args.push(head_oid.as_str().to_string());
+        merge_tree_args.push(params.their_commit.as_str().to_string());
+
+        let merge_tree_output = self.git_command_with(
+            crate::cmd::command::GitCommandParams::new(merge_tree_args)
+                .unchecked(),
+        )?;
+
+        let stdout = merge_tree_output.stdout_lossy();
+        let tree_oid_str = stdout.lines().next().unwrap_or("").trim();
+
+        if tree_oid_str.is_empty() {
+            if !merge_tree_output.success {
+                return Err(GitError::CommandFailed {
+                    status_code: merge_tree_output.status_code,
+                    stderr: merge_tree_output.stderr_lossy(),
+                });
+            }
+            return Err(GitError::ParseError(
+                "merge-tree produced no tree OID".to_string(),
+            ));
+        }
+
+        let tree_oid = ObjectId::new(tree_oid_str);
+        let their_info = self.commit_info(params.their_commit.clone())?;
+        let squash_message = their_info.message.clone();
+        let commit_tree_args = vec![
+            "commit-tree".to_string(),
+            tree_oid.as_str().to_string(),
+            "-p".to_string(),
+            head_oid.as_str().to_string(),
+            "-F".to_string(),
+            "-".to_string(),
+        ];
+        let author_timestamp = format_git_timestamp(
+            their_info.author.time_secs,
+            their_info.author.offset_minutes,
+        );
+        let committer_timestamp = format_git_timestamp(
+            their_info.committer.time_secs,
+            their_info.committer.offset_minutes,
+        );
+
+        let commit_output = self.git_command_with(
+            crate::cmd::command::GitCommandParams::new(commit_tree_args)
+                .with_stdin(squash_message.as_bytes().to_vec())
+                .with_env(
+                    "GIT_AUTHOR_NAME".to_string(),
+                    their_info.author.name.clone(),
+                )
+                .with_env(
+                    "GIT_AUTHOR_EMAIL".to_string(),
+                    their_info.author.email.clone(),
+                )
+                .with_env("GIT_AUTHOR_DATE".to_string(), author_timestamp)
+                .with_env(
+                    "GIT_COMMITTER_NAME".to_string(),
+                    their_info.committer.name.clone(),
+                )
+                .with_env(
+                    "GIT_COMMITTER_EMAIL".to_string(),
+                    their_info.committer.email.clone(),
+                )
+                .with_env(
+                    "GIT_COMMITTER_DATE".to_string(),
+                    committer_timestamp,
+                ),
+        )?;
+
+        let stdout_str = commit_output.stdout_lossy();
+        let commit_oid_str = stdout_str.trim();
+        if commit_oid_str.is_empty() {
+            return Err(GitError::CommandFailed {
+                status_code: commit_output.status_code,
+                stderr: commit_output.stderr_lossy(),
+            });
+        }
+
+        Ok(ObjectId::new(commit_oid_str))
+    }
+}
diff --git a/lib/git/cmd/mod.rs b/lib/git/cmd/mod.rs
new file mode 100644
index 0000000..a5fc408
--- /dev/null
+++ b/lib/git/cmd/mod.rs
@@ -0,0 +1,15 @@
+pub mod archive;
+pub mod blame;
+pub mod blob;
+pub mod branch;
+pub mod command;
+pub mod commit;
+pub mod diff;
+pub mod fork;
+pub mod init;
+pub mod merge;
+pub mod oid;
+pub mod parse;
+pub mod tag;
+pub mod tagger;
+pub mod tree;
diff --git a/lib/git/cmd/oid.rs b/lib/git/cmd/oid.rs
new file mode 100644
index 0000000..beb134a
--- /dev/null
+++ b/lib/git/cmd/oid.rs
@@ -0,0 +1,34 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, Clone, Debug, PartialEq, Eq)]
+pub struct ObjectId(pub String);
+
+impl ObjectId {
+    pub fn new(hex: impl AsRef<str>) -> Self {
+        Self(hex.as_ref().to_lowercase())
+    }
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+impl std::fmt::Display for ObjectId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl AsRef<str> for ObjectId {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl TryFrom<&ObjectId> for gix::hash::ObjectId {
+    type Error = crate::errors::GitError;
+
+    fn try_from(id: &ObjectId) -> Result<Self, Self::Error> {
+        gix::hash::ObjectId::from_hex(id.as_str().as_bytes()).map_err(|e| {
+            crate::errors::GitError::InvalidOid(format!("invalid hex oid: {e}"))
+        })
+    }
+}
diff --git a/lib/git/cmd/parse.rs b/lib/git/cmd/parse.rs
new file mode 100644
index 0000000..e67f37c
--- /dev/null
+++ b/lib/git/cmd/parse.rs
@@ -0,0 +1,45 @@
+pub fn parse_timezone_offset(tz: &str) -> crate::errors::GitResult<i32> {
+    use crate::errors::GitError;
+
+    if tz.len() != 5 {
+        return Err(GitError::ParseError(format!(
+            "invalid timezone format: {tz}"
+        )));
+    }
+
+    let sign: i32 = if tz.starts_with('+') {
+        1
+    } else if tz.starts_with('-') {
+        -1
+    } else {
+        return Err(GitError::ParseError(format!(
+            "invalid timezone sign: {tz}"
+        )));
+    };
+
+    let hours: i32 = tz[1..3].parse().map_err(|_| {
+        GitError::ParseError(format!("invalid timezone hours: {tz}"))
+    })?;
+    let minutes: i32 = tz[3..5].parse().map_err(|_| {
+        GitError::ParseError(format!("invalid timezone minutes: {tz}"))
+    })?;
+
+    Ok(sign * (hours * 60 + minutes))
+}
+pub fn parse_iso_timezone(iso_date: &str) -> crate::errors::GitResult<i32> {
+    let tz_part =
+        iso_date.rsplit_once(' ').map(|(_, tz)| tz).ok_or_else(|| {
+            crate::errors::GitError::ParseError(format!(
+                "ISO date missing timezone: {iso_date}"
+            ))
+        })?;
+
+    parse_timezone_offset(tz_part)
+}
+pub fn format_git_timestamp(secs: i64, offset_minutes: i32) -> String {
+    let sign = if offset_minutes >= 0 { '+' } else { '-' };
+    let abs_offset = offset_minutes.abs();
+    let hours = abs_offset / 60;
+    let mins = abs_offset % 60;
+    format!("{} {}{:02}{:02}", secs, sign, hours, mins)
+}
diff --git a/lib/git/cmd/tag/mod.rs b/lib/git/cmd/tag/mod.rs
new file mode 100644
index 0000000..bc5eae4
--- /dev/null
+++ b/lib/git/cmd/tag/mod.rs
@@ -0,0 +1,33 @@
+use serde::{Deserialize, Serialize};
+
+use crate::cmd::oid::ObjectId;
+
+pub mod tag_count;
+pub mod tag_delete;
+pub mod tag_info;
+pub mod tag_init;
+pub mod tag_list;
+pub mod tag_rename;
+pub mod tag_summary;
+pub mod tag_upmsg;
+
+pub use tag_delete::TagDeleteParams;
+pub use tag_init::TagInitParams;
+pub use tag_rename::TagRenameParams;
+pub use tag_upmsg::TagUpdateMessageParams;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TagItem {
+    pub name: String,
+    pub oid: ObjectId,
+    pub target: ObjectId,
+    pub is_annotated: bool,
+    pub message: Option<String>,
+    pub tagger: Option<String>,
+    pub tagger_email: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TagSummary {
+    pub total_count: usize,
+}
diff --git a/lib/git/cmd/tag/tag_count.rs b/lib/git/cmd/tag/tag_count.rs
new file mode 100644
index 0000000..55a2794
--- /dev/null
+++ b/lib/git/cmd/tag/tag_count.rs
@@ -0,0 +1,9 @@
+use crate::{bare::GitBare, errors::GitResult};
+
+impl GitBare {
+    pub fn tag_count(&self) -> GitResult<usize> {
+        let repo = self.gix_repo()?;
+        let platform = repo.references()?;
+        Ok(platform.tags()?.count())
+    }
+}
diff --git a/lib/git/cmd/tag/tag_delete.rs b/lib/git/cmd/tag/tag_delete.rs
new file mode 100644
index 0000000..6a38be9
--- /dev/null
+++ b/lib/git/cmd/tag/tag_delete.rs
@@ -0,0 +1,38 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::command::GitCommandParams,
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TagDeleteParams {
+    pub name: String,
+}
+
+impl GitBare {
+    pub fn tag_delete(&self, params: TagDeleteParams) -> GitResult<()> {
+        let cmd_params = GitCommandParams::new(vec![
+            "tag".to_string(),
+            "-d".to_string(),
+            params.name.clone(),
+        ])
+        .trusted()
+        .unchecked();
+
+        let output = self.git_command_with(cmd_params)?;
+        if !output.success {
+            let stderr = output.stderr_lossy();
+            if stderr.contains("not found") {
+                return Err(GitError::RefNotFound(params.name));
+            }
+            return Err(GitError::CommandFailed {
+                status_code: output.status_code,
+                stderr,
+            });
+        }
+
+        Ok(())
+    }
+}
diff --git a/lib/git/cmd/tag/tag_info.rs b/lib/git/cmd/tag/tag_info.rs
new file mode 100644
index 0000000..b831bf4
--- /dev/null
+++ b/lib/git/cmd/tag/tag_info.rs
@@ -0,0 +1,70 @@
+use crate::{
+    bare::GitBare,
+    cmd::{oid::ObjectId, tag::TagItem},
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn tag_info(&self, name: String) -> GitResult<TagItem> {
+        let repo = self.gix_repo()?;
+        let ref_str = format!("refs/tags/{name}");
+        let mut reference = repo.find_reference(ref_str.as_str())?;
+
+        let short_name = reference.name().shorten().to_string();
+        let direct_id_hex = reference
+            .target()
+            .try_id()
+            .map(|id| id.to_hex().to_string())
+            .ok_or_else(|| {
+                GitError::Internal("tag ref has no direct target".to_string())
+            })?;
+
+        let direct_gix_id: gix::hash::ObjectId =
+            gix::hash::ObjectId::from_hex(direct_id_hex.as_bytes())
+                .map_err(|e| GitError::InvalidOid(e.to_string()))?;
+        let obj_header = repo.find_header(direct_gix_id)?;
+        let is_annotated = obj_header.kind() == gix::object::Kind::Tag;
+        let peeled_id = reference.peel_to_id()?;
+        let peeled_hex = peeled_id.detach().to_hex().to_string();
+
+        let (oid, target_oid) = if is_annotated {
+            (ObjectId::new(direct_id_hex), ObjectId::new(peeled_hex))
+        } else {
+            let target_oid = ObjectId::new(direct_id_hex);
+            (target_oid.clone(), target_oid)
+        };
+
+        let (message, tagger, tagger_email) = if is_annotated {
+            let tag_obj = repo.find_tag(direct_gix_id)?;
+            let decoded = tag_obj.decode()?;
+
+            let message = decoded.message.to_string().trim_end().to_string();
+            let msg = if message.is_empty() {
+                None
+            } else {
+                Some(message)
+            };
+
+            let (tg_name, tg_email) = decoded
+                .tagger()
+                .ok()
+                .flatten()
+                .map(|s| (Some(s.name.to_string()), Some(s.email.to_string())))
+                .unwrap_or((None, None));
+
+            (msg, tg_name, tg_email)
+        } else {
+            (None, None, None)
+        };
+
+        Ok(TagItem {
+            name: short_name,
+            oid,
+            target: target_oid,
+            is_annotated,
+            message,
+            tagger,
+            tagger_email,
+        })
+    }
+}
diff --git a/lib/git/cmd/tag/tag_init.rs b/lib/git/cmd/tag/tag_init.rs
new file mode 100644
index 0000000..feb2e15
--- /dev/null
+++ b/lib/git/cmd/tag/tag_init.rs
@@ -0,0 +1,83 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{command::GitCommandParams, oid::ObjectId, tagger::GitTagger},
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TagInitParams {
+    pub name: String,
+    pub target: ObjectId,
+    pub message: Option<String>,
+    pub tagger: Option<GitTagger>,
+    pub force: bool,
+}
+
+impl GitBare {
+    pub fn tag_init(&self, params: TagInitParams) -> GitResult<ObjectId> {
+        if let Some(message) = &params.message {
+            let mut cmd_args = vec!["tag".to_string(), "-a".to_string()];
+            if params.force {
+                cmd_args.push("--force".to_string());
+            }
+            cmd_args.push(params.name.clone());
+            cmd_args.push(params.target.as_str().to_string());
+            cmd_args.push("-F".to_string());
+            cmd_args.push("-".to_string());
+
+            let mut cmd_params = GitCommandParams::new(cmd_args)
+                .trusted()
+                .with_stdin(message.as_bytes().to_vec());
+
+            if let Some(tagger) = &params.tagger {
+                cmd_params = cmd_params
+                    .with_env(
+                        "GIT_COMMITTER_NAME".to_string(),
+                        tagger.name.clone(),
+                    )
+                    .with_env(
+                        "GIT_COMMITTER_EMAIL".to_string(),
+                        tagger.email.clone(),
+                    );
+            }
+
+            let output = self.git_command_with(cmd_params)?;
+            if !output.success {
+                return Err(GitError::CommandFailed {
+                    status_code: output.status_code,
+                    stderr: output.stderr_lossy(),
+                });
+            }
+        } else {
+            let mut cmd_args = vec!["tag".to_string()];
+            if params.force {
+                cmd_args.push("--force".to_string());
+            }
+            cmd_args.push(params.name.clone());
+            cmd_args.push(params.target.as_str().to_string());
+
+            let output = self.git_command_trusted(cmd_args)?;
+            if !output.success {
+                return Err(GitError::CommandFailed {
+                    status_code: output.status_code,
+                    stderr: output.stderr_lossy(),
+                });
+            }
+        }
+        let repo = self.gix_repo()?;
+        let refname = format!("refs/tags/{}", params.name);
+        let ref_name_gix = gix::refs::PartialName::try_from(refname.as_str())
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+        let tag_ref = repo
+            .find_reference(&ref_name_gix)
+            .map_err(|e| GitError::Gix(e.to_string()))?;
+        let target = tag_ref.target();
+        let target_id = target.try_id().ok_or_else(|| {
+            GitError::Gix(format!("tag ref '{}' has no direct target", refname))
+        })?;
+
+        Ok(ObjectId::new(target_id.to_hex().to_string()))
+    }
+}
diff --git a/lib/git/cmd/tag/tag_list.rs b/lib/git/cmd/tag/tag_list.rs
new file mode 100644
index 0000000..9d773f1
--- /dev/null
+++ b/lib/git/cmd/tag/tag_list.rs
@@ -0,0 +1,59 @@
+use crate::{
+    bare::GitBare,
+    cmd::{oid::ObjectId, tag::TagItem},
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn tag_list(&self) -> GitResult<Vec<TagItem>> {
+        let repo = self.gix_repo()?;
+        let platform = repo.references()?;
+        let tags_iter = platform.tags()?;
+
+        let mut items = Vec::new();
+        for ref_result in tags_iter {
+            let mut reference = ref_result?;
+            let name = reference.name().shorten().to_string();
+            let direct_id_hex = reference
+                .target()
+                .try_id()
+                .map(|id| id.to_hex().to_string())
+                .ok_or_else(|| {
+                    crate::errors::GitError::Internal(
+                        "tag ref has no direct target".to_string(),
+                    )
+                })?;
+
+            let direct_gix_id: gix::hash::ObjectId =
+                gix::hash::ObjectId::from_hex(direct_id_hex.as_bytes())
+                    .map_err(|e| {
+                        crate::errors::GitError::InvalidOid(e.to_string())
+                    })?;
+            let is_annotated = repo
+                .find_header(direct_gix_id)
+                .ok()
+                .is_some_and(|h| h.kind() == gix::object::Kind::Tag);
+            let peeled_id = reference.peel_to_id()?;
+            let peeled_hex = peeled_id.detach().to_hex().to_string();
+
+            let (oid, target_oid) = if is_annotated {
+                (ObjectId::new(direct_id_hex), ObjectId::new(peeled_hex))
+            } else {
+                let target_oid = ObjectId::new(direct_id_hex);
+                (target_oid.clone(), target_oid)
+            };
+
+            items.push(TagItem {
+                name,
+                oid,
+                target: target_oid,
+                is_annotated,
+                message: None,
+                tagger: None,
+                tagger_email: None,
+            });
+        }
+
+        Ok(items)
+    }
+}
diff --git a/lib/git/cmd/tag/tag_rename.rs b/lib/git/cmd/tag/tag_rename.rs
new file mode 100644
index 0000000..b9cba40
--- /dev/null
+++ b/lib/git/cmd/tag/tag_rename.rs
@@ -0,0 +1,44 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        tag::{tag_delete::TagDeleteParams, tag_init::TagInitParams},
+        tagger::GitTagger,
+    },
+    errors::GitResult,
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TagRenameParams {
+    pub old_name: String,
+    pub new_name: String,
+    pub force: bool,
+}
+
+impl GitBare {
+    pub fn tag_rename(&self, params: TagRenameParams) -> GitResult<()> {
+        let old_info = self.tag_info(params.old_name.clone())?;
+        let init_params = TagInitParams {
+            name: params.new_name.clone(),
+            target: old_info.target.clone(),
+            message: old_info.message.clone(),
+            tagger: if old_info.is_annotated {
+                Some(GitTagger {
+                    name: old_info.tagger.clone().unwrap_or_default(),
+                    email: old_info.tagger_email.clone().unwrap_or_default(),
+                })
+            } else {
+                None
+            },
+            force: params.force,
+        };
+
+        self.tag_init(init_params)?;
+        self.tag_delete(TagDeleteParams {
+            name: params.old_name.clone(),
+        })?;
+
+        Ok(())
+    }
+}
diff --git a/lib/git/cmd/tag/tag_summary.rs b/lib/git/cmd/tag/tag_summary.rs
new file mode 100644
index 0000000..8ca06d9
--- /dev/null
+++ b/lib/git/cmd/tag/tag_summary.rs
@@ -0,0 +1,8 @@
+use crate::{bare::GitBare, cmd::tag::TagSummary, errors::GitResult};
+
+impl GitBare {
+    pub fn tag_summary(&self) -> GitResult<TagSummary> {
+        let total_count = self.tag_count()?;
+        Ok(TagSummary { total_count })
+    }
+}
diff --git a/lib/git/cmd/tag/tag_upmsg.rs b/lib/git/cmd/tag/tag_upmsg.rs
new file mode 100644
index 0000000..bc4b331
--- /dev/null
+++ b/lib/git/cmd/tag/tag_upmsg.rs
@@ -0,0 +1,40 @@
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    bare::GitBare,
+    cmd::{
+        oid::ObjectId,
+        tag::{tag_delete::TagDeleteParams, tag_init::TagInitParams},
+        tagger::GitTagger,
+    },
+    errors::GitResult,
+};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TagUpdateMessageParams {
+    pub name: String,
+    pub message: String,
+    pub tagger: GitTagger,
+    pub force: bool,
+}
+
+impl GitBare {
+    pub fn tag_update_message(
+        &self,
+        params: TagUpdateMessageParams,
+    ) -> GitResult<ObjectId> {
+        let current_info = self.tag_info(params.name.clone())?;
+        self.tag_delete(TagDeleteParams {
+            name: params.name.clone(),
+        })?;
+        let init_params = TagInitParams {
+            name: params.name.clone(),
+            target: current_info.target.clone(),
+            message: Some(params.message.clone()),
+            tagger: Some(params.tagger.clone()),
+            force: params.force,
+        };
+
+        self.tag_init(init_params)
+    }
+}
diff --git a/lib/git/cmd/tagger.rs b/lib/git/cmd/tagger.rs
new file mode 100644
index 0000000..29cc03c
--- /dev/null
+++ b/lib/git/cmd/tagger.rs
@@ -0,0 +1,7 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct GitTagger {
+    pub name: String,
+    pub email: String,
+}
diff --git a/lib/git/cmd/tree/mod.rs b/lib/git/cmd/tree/mod.rs
new file mode 100644
index 0000000..b8a1187
--- /dev/null
+++ b/lib/git/cmd/tree/mod.rs
@@ -0,0 +1,34 @@
+use serde::{Deserialize, Serialize};
+
+use crate::cmd::oid::ObjectId;
+
+pub mod resolve_tree;
+pub mod tree_entry;
+pub mod tree_entry_by_path_from_commit;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TreeInfo {
+    pub oid: ObjectId,
+    pub entry_count: usize,
+    pub is_empty: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TreeEntry {
+    pub name: String,
+    pub oid: ObjectId,
+    pub kind: TreeKind,
+    pub filemode: u32,
+    pub is_binary: bool,
+    pub is_lfs: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub enum TreeKind {
+    #[serde(rename = "blob")]
+    Blob,
+    #[serde(rename = "tree")]
+    Tree,
+    #[serde(rename = "lfs_pointer")]
+    LfsPointer,
+}
diff --git a/lib/git/cmd/tree/resolve_tree.rs b/lib/git/cmd/tree/resolve_tree.rs
new file mode 100644
index 0000000..282222f
--- /dev/null
+++ b/lib/git/cmd/tree/resolve_tree.rs
@@ -0,0 +1,29 @@
+use crate::{
+    bare::GitBare,
+    cmd::{oid::ObjectId, tree::TreeInfo},
+    errors::{GitError, GitResult},
+};
+
+impl GitBare {
+    pub fn resolve_tree(&self, oid: ObjectId) -> GitResult<TreeInfo> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&oid).try_into()?;
+        let header = repo.find_header(gix_id)?;
+        if header.kind() != gix::object::Kind::Tree {
+            return Err(GitError::ParseError(format!(
+                "object {} is not a tree (type: {})",
+                oid,
+                header.kind()
+            )));
+        }
+
+        let gix_tree = repo.find_tree(gix_id)?;
+        let entry_count = gix_tree.iter().count();
+
+        Ok(TreeInfo {
+            oid,
+            entry_count,
+            is_empty: entry_count == 0,
+        })
+    }
+}
diff --git a/lib/git/cmd/tree/tree_entry.rs b/lib/git/cmd/tree/tree_entry.rs
new file mode 100644
index 0000000..9ff9614
--- /dev/null
+++ b/lib/git/cmd/tree/tree_entry.rs
@@ -0,0 +1,143 @@
+use crate::{
+    bare::GitBare,
+    cmd::{
+        oid::ObjectId,
+        tree::{TreeEntry, TreeKind},
+    },
+    errors::{GitError, GitResult},
+};
+
+const LFS_POINTER_PREFIX: &[u8] = b"version https://git-lfs.github.com/spec/v";
+const LFS_OID_MARKER: &[u8] = b"\noid sha256:";
+const LFS_POINTER_MAX_SIZE: usize = 512;
+
+impl GitBare {
+    fn blob_is_lfs_pointer(&self, id: ObjectId) -> GitResult<bool> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&id).try_into()?;
+        let blob = repo
+            .find_blob(gix_id)
+            .map_err(|_| GitError::ObjectNotFound(id.as_str().to_string()))?;
+
+        if blob.data.len() > LFS_POINTER_MAX_SIZE {
+            return Ok(false);
+        }
+
+        let data = &blob.data;
+        Ok(data.starts_with(LFS_POINTER_PREFIX)
+            && contains_subslice(data, LFS_OID_MARKER))
+    }
+
+    pub fn tree_entries(&self, tree: ObjectId) -> GitResult<Vec<TreeEntry>> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&tree).try_into()?;
+        let gix_tree = repo.find_tree(gix_id)?;
+
+        let mut entries = Vec::new();
+        for entry_result in gix_tree.iter() {
+            let entry = entry_result?;
+            let name = entry.inner.filename.to_string();
+            let oid = ObjectId::new(entry.inner.oid.to_hex().to_string());
+
+            let is_tree = entry.inner.mode.is_tree();
+            let is_lfs = if !is_tree {
+                self.blob_is_lfs_pointer(oid.clone()).unwrap_or(false)
+            } else {
+                false
+            };
+
+            let kind = if is_tree {
+                TreeKind::Tree
+            } else if is_lfs {
+                TreeKind::LfsPointer
+            } else {
+                TreeKind::Blob
+            };
+
+            let filemode = entry.inner.mode.value() as u32;
+
+            let is_binary = match kind {
+                TreeKind::LfsPointer => false,
+                TreeKind::Blob => {
+                    self.blob_is_binary(oid.clone()).unwrap_or(false)
+                }
+                TreeKind::Tree => false,
+            };
+
+            entries.push(TreeEntry {
+                name,
+                oid,
+                kind,
+                filemode,
+                is_binary,
+                is_lfs,
+            });
+        }
+
+        Ok(entries)
+    }
+
+    pub fn tree_entry_by_path(
+        &self,
+        tree: ObjectId,
+        path: String,
+    ) -> GitResult<TreeEntry> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&tree).try_into()?;
+        let gix_tree = repo.find_tree(gix_id)?;
+
+        let entry = gix_tree.find_entry(path.as_str()).ok_or_else(|| {
+            GitError::ObjectNotFound(format!(
+                "path '{}' not found in tree {}",
+                path, tree
+            ))
+        })?;
+
+        let name = entry.inner.filename.to_string();
+        let oid = ObjectId::new(entry.inner.oid.to_hex().to_string());
+
+        let is_tree = entry.inner.mode.is_tree();
+        let is_lfs = if !is_tree {
+            self.blob_is_lfs_pointer(oid.clone()).unwrap_or(false)
+        } else {
+            false
+        };
+
+        let kind = if is_tree {
+            TreeKind::Tree
+        } else if is_lfs {
+            TreeKind::LfsPointer
+        } else {
+            TreeKind::Blob
+        };
+
+        let filemode = entry.inner.mode.value() as u32;
+
+        let is_binary = match kind {
+            TreeKind::LfsPointer => false,
+            TreeKind::Blob => self.blob_is_binary(oid.clone()).unwrap_or(false),
+            TreeKind::Tree => false,
+        };
+
+        Ok(TreeEntry {
+            name,
+            oid,
+            kind,
+            filemode,
+            is_binary,
+            is_lfs,
+        })
+    }
+}
+
+fn contains_subslice(data: &[u8], pattern: &[u8]) -> bool {
+    if pattern.len() > data.len() {
+        return false;
+    }
+    for window in data.windows(pattern.len()) {
+        if window == pattern {
+            return true;
+        }
+    }
+    false
+}
diff --git a/lib/git/cmd/tree/tree_entry_by_path_from_commit.rs b/lib/git/cmd/tree/tree_entry_by_path_from_commit.rs
new file mode 100644
index 0000000..7fdcf9f
--- /dev/null
+++ b/lib/git/cmd/tree/tree_entry_by_path_from_commit.rs
@@ -0,0 +1,22 @@
+use crate::{
+    bare::GitBare,
+    cmd::{oid::ObjectId, tree::TreeEntry},
+    errors::GitResult,
+};
+
+impl GitBare {
+    pub fn tree_entry_by_path_from_commit(
+        &self,
+        commit: ObjectId,
+        path: String,
+    ) -> GitResult<TreeEntry> {
+        let repo = self.gix_repo()?;
+        let gix_id: gix::hash::ObjectId = (&commit).try_into()?;
+
+        let gix_commit = repo.find_commit(gix_id)?;
+        let tree_id = gix_commit.tree_id()?.detach();
+        let tree_oid = ObjectId::new(tree_id.to_hex().to_string());
+
+        self.tree_entry_by_path(tree_oid, path)
+    }
+}
diff --git a/lib/git/errors.rs b/lib/git/errors.rs
new file mode 100644
index 0000000..97bad42
--- /dev/null
+++ b/lib/git/errors.rs
@@ -0,0 +1,81 @@
+pub type GitResult<T> = Result<T, GitError>;
+
+#[derive(Debug, thiserror::Error)]
+pub enum GitError {
+    #[error("repository is not bare")]
+    NotBareRepository,
+    #[error("git command failed with status {status_code:?}: {stderr}")]
+    CommandFailed {
+        status_code: Option<i32>,
+        stderr: String,
+    },
+    #[error("unsafe git command rejected: {0}")]
+    UnsafeCommand(String),
+    #[error("object not found: {0}")]
+    ObjectNotFound(String),
+    #[error("reference not found: {0}")]
+    RefNotFound(String),
+    #[error("parse error: {0}")]
+    ParseError(String),
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+    #[error("gix error: {0}")]
+    Gix(String),
+    #[error("database error: {0}")]
+    DatabaseError(db::sqlx::Error),
+    #[error("repository not found")]
+    RepoNotFound,
+    #[error("internal error: {0}")]
+    Internal(String),
+    #[error("not found: {0}")]
+    NotFound(String),
+    #[error("invalid oid: {0}")]
+    InvalidOid(String),
+    #[error("locked: {0}")]
+    Locked(String),
+    #[error("permission denied: {0}")]
+    PermissionDenied(String),
+    #[error("authentication failed: {0}")]
+    AuthFailed(String),
+}
+
+impl From<db::sqlx::Error> for GitError {
+    fn from(e: db::sqlx::Error) -> Self {
+        GitError::DatabaseError(e)
+    }
+}
+
+macro_rules! impl_gix_error {
+    ($err_type:path) => {
+        impl From<$err_type> for GitError {
+            fn from(e: $err_type) -> Self {
+                GitError::Gix(e.to_string())
+            }
+        }
+    };
+}
+
+impl_gix_error!(gix::object::find::existing::Error);
+impl_gix_error!(gix::object::find::existing::with_conversion::Error);
+impl_gix_error!(gix::object::find::Error);
+impl_gix_error!(gix::reference::iter::Error);
+impl_gix_error!(gix::reference::iter::init::Error);
+impl_gix_error!(gix::reference::find::existing::Error);
+impl_gix_error!(gix::reference::find::Error);
+impl_gix_error!(gix::reference::head_id::Error);
+impl_gix_error!(gix::repository::merge_bases_many::Error);
+impl_gix_error!(gix::reference::peel::Error);
+impl_gix_error!(gix::repository::blame_file::Error);
+impl_gix_error!(gix::blame::Error);
+impl_gix_error!(gix::revision::walk::Error);
+impl_gix_error!(gix::revision::walk::iter::Error);
+impl_gix_error!(gix::revision::spec::parse::single::Error);
+impl_gix_error!(gix::open::Error);
+impl_gix_error!(gix::objs::decode::Error);
+impl_gix_error!(gix::date::Error);
+
+impl From<Box<dyn std::error::Error + Send + Sync>> for GitError {
+    fn from(e: Box<dyn std::error::Error + Send + Sync>) -> Self {
+        GitError::Gix(e.to_string())
+    }
+}
diff --git a/lib/git/graphql/blob.rs b/lib/git/graphql/blob.rs
new file mode 100644
index 0000000..ccf5552
--- /dev/null
+++ b/lib/git/graphql/blob.rs
@@ -0,0 +1,93 @@
+use std::time::Duration;
+
+use juniper::graphql_object;
+
+use crate::{
+    cmd::{
+        blob::{blob_load::BlobLoadParams, blob_size::BlobSizeParams},
+        oid::ObjectId,
+    },
+    graphql::{
+        GraphqlContext,
+        cache_helper::{IMMUTABLE_TTL, cache_key, cached_json},
+    },
+};
+
+const BLOB_SIZE_TTL: Duration = IMMUTABLE_TTL;
+
+#[derive(Clone, serde::Serialize, serde::Deserialize)]
+pub struct BlobResult {
+    pub oid: String,
+    pub size: i32,
+    pub is_binary: bool,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl BlobResult {
+    fn oid(&self) -> &str {
+        &self.oid
+    }
+    fn size(&self) -> i32 {
+        self.size
+    }
+    fn is_binary(&self) -> bool {
+        self.is_binary
+    }
+}
+
+pub async fn resolve_blob_size(
+    ctx: &GraphqlContext,
+    oid: String,
+) -> anyhow::Result<i32> {
+    let key = cache_key("query:git:blob_size", &[&oid]);
+    cached_json(&ctx.cache, &key, BLOB_SIZE_TTL, || {
+        let repo = ctx.repo.clone();
+        let oid_obj = ObjectId::new(&oid);
+        async move {
+            let size = tokio::task::spawn_blocking(move || {
+                repo.blob_size(&BlobSizeParams {
+                    id: oid_obj,
+                    path: String::new(),
+                })
+            })
+            .await?
+            .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(size as i32)
+        }
+    })
+    .await
+}
+
+pub async fn resolve_blob(
+    ctx: &GraphqlContext,
+    oid: String,
+) -> anyhow::Result<BlobResult> {
+    let repo = ctx.repo.clone();
+    let oid_obj = ObjectId::new(&oid);
+    let result = tokio::task::spawn_blocking(move || {
+        let size = repo.blob_size(&BlobSizeParams {
+            id: oid_obj.clone(),
+            path: String::new(),
+        })?;
+        let loaded = repo.blob_load(&BlobLoadParams {
+            id: oid_obj,
+            path: String::new(),
+        })?;
+        Ok::<(u64, Vec<u8>, String), crate::errors::GitError>((
+            size,
+            loaded.blob,
+            oid,
+        ))
+    })
+    .await?
+    .map_err(|e| anyhow::anyhow!(e))?;
+
+    let (size, bytes, oid_str) = result;
+    let is_binary = bytes.contains(&0);
+
+    Ok(BlobResult {
+        oid: oid_str,
+        size: size as i32,
+        is_binary,
+    })
+}
diff --git a/lib/git/graphql/branch.rs b/lib/git/graphql/branch.rs
new file mode 100644
index 0000000..e3d61d1
--- /dev/null
+++ b/lib/git/graphql/branch.rs
@@ -0,0 +1,173 @@
+use std::time::Duration;
+
+use juniper::graphql_object;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    cmd::branch::{branch_list::BranchListItem, branch_summary::BranchSummary},
+    graphql::{
+        GraphqlContext,
+        cache_helper::{
+            MUTABLE_TTL, cached_json, mutable_cache_key, repo_revision,
+        },
+    },
+};
+
+const BRANCH_TTL: Duration = MUTABLE_TTL;
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct BranchGql {
+    pub name: String,
+    pub oid: String,
+    pub is_head: bool,
+    pub is_remote: bool,
+    pub is_current: bool,
+    pub upstream: Option<String>,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl BranchGql {
+    fn name(&self) -> &str {
+        &self.name
+    }
+    fn oid(&self) -> &str {
+        &self.oid
+    }
+    fn is_head(&self) -> bool {
+        self.is_head
+    }
+    fn is_remote(&self) -> bool {
+        self.is_remote
+    }
+    fn is_current(&self) -> bool {
+        self.is_current
+    }
+    fn upstream(&self) -> Option<&str> {
+        self.upstream.as_deref()
+    }
+}
+
+impl From<BranchListItem> for BranchGql {
+    fn from(item: BranchListItem) -> Self {
+        BranchGql {
+            name: item.name,
+            oid: item.oid.0,
+            is_head: item.is_head,
+            is_remote: item.is_remote,
+            is_current: item.is_current,
+            upstream: item.upstream,
+        }
+    }
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct BranchSummaryGql {
+    pub local_count: i32,
+    pub remote_count: i32,
+    pub all_count: i32,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl BranchSummaryGql {
+    fn local_count(&self) -> i32 {
+        self.local_count
+    }
+    fn remote_count(&self) -> i32 {
+        self.remote_count
+    }
+    fn all_count(&self) -> i32 {
+        self.all_count
+    }
+}
+
+impl From<BranchSummary> for BranchSummaryGql {
+    fn from(s: BranchSummary) -> Self {
+        BranchSummaryGql {
+            local_count: s.local_count as i32,
+            remote_count: s.remote_count as i32,
+            all_count: s.all_count as i32,
+        }
+    }
+}
+
+pub async fn resolve_branches(
+    ctx: &GraphqlContext,
+) -> anyhow::Result<Vec<BranchGql>> {
+    let revision = repo_revision(ctx).await;
+    let key = mutable_cache_key(ctx, "query:git:branches", &[], &revision);
+    cached_json(&ctx.cache, &key, BRANCH_TTL, || {
+        let repo = ctx.repo.clone();
+        async move {
+            let items =
+                tokio::task::spawn_blocking(move || repo.branch_list_all())
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(items.into_iter().map(BranchGql::from).collect())
+        }
+    })
+    .await
+}
+
+pub async fn resolve_branch(
+    ctx: &GraphqlContext,
+    name: String,
+) -> anyhow::Result<BranchGql> {
+    let revision = repo_revision(ctx).await;
+    let key = mutable_cache_key(ctx, "query:git:branch", &[&name], &revision);
+    cached_json(&ctx.cache, &key, BRANCH_TTL, || {
+        let repo = ctx.repo.clone();
+        let branch_name = name.clone();
+        async move {
+            let item = tokio::task::spawn_blocking(move || {
+                repo.branch_info(branch_name)
+            })
+            .await?
+            .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(BranchGql::from(item))
+        }
+    })
+    .await
+}
+
+pub async fn resolve_head_branch(
+    ctx: &GraphqlContext,
+) -> anyhow::Result<BranchGql> {
+    let revision = repo_revision(ctx).await;
+    let key = mutable_cache_key(ctx, "query:git:head_branch", &[], &revision);
+    cached_json(&ctx.cache, &key, BRANCH_TTL, || {
+        let repo1 = ctx.repo.clone();
+        let repo2 = ctx.repo.clone();
+        async move {
+            let head_name =
+                tokio::task::spawn_blocking(move || repo1.branch_head_name())
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            let branch = tokio::task::spawn_blocking(move || {
+                repo2.branch_info(head_name)
+            })
+            .await?
+            .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(BranchGql::from(branch))
+        }
+    })
+    .await
+}
+
+pub async fn resolve_branch_summary(
+    ctx: &GraphqlContext,
+) -> anyhow::Result<BranchSummaryGql> {
+    let revision = repo_revision(ctx).await;
+    let key =
+        mutable_cache_key(ctx, "query:git:branch_summary", &[], &revision);
+    cached_json(&ctx.cache, &key, BRANCH_TTL, || {
+        let repo = ctx.repo.clone();
+        async move {
+            let summary =
+                tokio::task::spawn_blocking(move || repo.branch_summary())
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(BranchSummaryGql::from(summary))
+        }
+    })
+    .await
+}
diff --git a/lib/git/graphql/cache_helper.rs b/lib/git/graphql/cache_helper.rs
new file mode 100644
index 0000000..17ad6f2
--- /dev/null
+++ b/lib/git/graphql/cache_helper.rs
@@ -0,0 +1,93 @@
+use std::{fmt::Display, future::Future, time::Duration};
+
+use cache::AppCache;
+use serde::{Serialize, de::DeserializeOwned};
+
+use crate::{bare::GitBare, graphql::GraphqlContext};
+
+const KEY_SEPARATOR: &str = ":";
+
+pub fn cache_key(namespace: &str, parts: &[&str]) -> String {
+    let mut segments: Vec<&str> = vec![namespace];
+    for part in parts {
+        if !part.is_empty() {
+            segments.push(part);
+        }
+    }
+    segments.join(KEY_SEPARATOR)
+}
+
+pub fn cache_key_with_revision(
+    namespace: &str,
+    revision: impl Display,
+    parts: &[&str],
+) -> String {
+    let mut key = cache_key(namespace, parts);
+    key.push_str(KEY_SEPARATOR);
+    key.push_str(&revision.to_string());
+    key
+}
+
+fn path_hash(repo: &GitBare) -> String {
+    let path_str = repo.bare_dir.to_string_lossy();
+    let hash = simple_hash(&path_str);
+    hash[..8].to_string()
+}
+
+fn simple_hash(s: &str) -> String {
+    let mut h: u64 = 0;
+    for b in s.bytes() {
+        h = h.wrapping_mul(31).wrapping_add(b as u64);
+    }
+    format!("{:016x}", h)
+}
+
+pub async fn repo_revision(ctx: &GraphqlContext) -> String {
+    let repo = ctx.repo.clone();
+    let result = tokio::task::spawn_blocking(move || {
+        repo.git_command_stdout(vec![
+            "rev-parse".to_string(),
+            "HEAD".to_string(),
+        ])
+    })
+    .await;
+    match result {
+        Ok(Ok(oid)) => oid.trim().to_string(),
+        _ => "unknown".to_string(),
+    }
+}
+
+pub fn mutable_cache_key(
+    ctx: &GraphqlContext,
+    namespace: &str,
+    parts: &[&str],
+    revision: &str,
+) -> String {
+    let ph = path_hash(&ctx.repo);
+    let mut all_parts: Vec<&str> = vec![&ph];
+    all_parts.extend_from_slice(parts);
+    cache_key_with_revision(namespace, revision, &all_parts)
+}
+
+pub async fn cached_json<T, F, Fut>(
+    cache: &AppCache,
+    key: &str,
+    _ttl: Duration,
+    build: F,
+) -> anyhow::Result<T>
+where
+    T: Serialize + DeserializeOwned,
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = anyhow::Result<T>>,
+{
+    if let Ok(Some(cached)) = cache.get::<T>(key).await {
+        return Ok(cached);
+    }
+
+    let value = build().await?;
+    cache.set(key, &value).await.ok();
+    Ok(value)
+}
+
+pub const IMMUTABLE_TTL: Duration = Duration::from_secs(86400);
+pub const MUTABLE_TTL: Duration = Duration::from_secs(300);
diff --git a/lib/git/graphql/commit.rs b/lib/git/graphql/commit.rs
new file mode 100644
index 0000000..e4d8996
--- /dev/null
+++ b/lib/git/graphql/commit.rs
@@ -0,0 +1,224 @@
+use std::time::Duration;
+
+use juniper::graphql_object;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    cmd::{
+        commit::{
+            CommitMeta, CommitSignature,
+            commit_summary::CommitSummary,
+            commit_walker::{CommitWalkParams, CommitWalkSort},
+        },
+        oid::ObjectId,
+    },
+    graphql::{
+        GraphqlContext,
+        cache_helper::{
+            IMMUTABLE_TTL, MUTABLE_TTL, cache_key, cached_json,
+            mutable_cache_key, repo_revision,
+        },
+    },
+};
+
+const COMMIT_TTL: Duration = IMMUTABLE_TTL;
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct CommitGql {
+    pub oid: String,
+    pub message: String,
+    pub summary: String,
+    pub author: CommitSignatureGql,
+    pub committer: CommitSignatureGql,
+    pub tree_id: String,
+    pub parent_ids: Vec<String>,
+    pub encoding: Option<String>,
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct CommitSignatureGql {
+    pub name: String,
+    pub email: String,
+    pub time_secs: f64,
+    pub offset_minutes: i32,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl CommitSignatureGql {
+    fn name(&self) -> &str {
+        &self.name
+    }
+    fn email(&self) -> &str {
+        &self.email
+    }
+    fn time_secs(&self) -> f64 {
+        self.time_secs
+    }
+    fn offset_minutes(&self) -> i32 {
+        self.offset_minutes
+    }
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl CommitGql {
+    fn oid(&self) -> &str {
+        &self.oid
+    }
+    fn message(&self) -> &str {
+        &self.message
+    }
+    fn summary(&self) -> &str {
+        &self.summary
+    }
+    fn author(&self) -> &CommitSignatureGql {
+        &self.author
+    }
+    fn committer(&self) -> &CommitSignatureGql {
+        &self.committer
+    }
+    fn tree_id(&self) -> &str {
+        &self.tree_id
+    }
+    fn parent_ids(&self) -> &[String] {
+        &self.parent_ids
+    }
+    fn encoding(&self) -> Option<&str> {
+        self.encoding.as_deref()
+    }
+}
+
+impl From<CommitSignature> for CommitSignatureGql {
+    fn from(s: CommitSignature) -> Self {
+        CommitSignatureGql {
+            name: s.name,
+            email: s.email,
+            time_secs: s.time_secs as f64,
+            offset_minutes: s.offset_minutes,
+        }
+    }
+}
+
+impl From<CommitMeta> for CommitGql {
+    fn from(m: CommitMeta) -> Self {
+        CommitGql {
+            oid: m.oid.0,
+            message: m.message,
+            summary: m.summary,
+            author: CommitSignatureGql::from(m.author),
+            committer: CommitSignatureGql::from(m.committer),
+            tree_id: m.tree_id.0,
+            parent_ids: m.parent_ids.iter().map(|p| p.0.clone()).collect(),
+            encoding: m.encoding,
+        }
+    }
+}
+
+pub async fn resolve_commit(
+    ctx: &GraphqlContext,
+    oid: String,
+) -> anyhow::Result<CommitGql> {
+    let key = cache_key("query:git:commit", &[&oid]);
+    cached_json(&ctx.cache, &key, COMMIT_TTL, || {
+        let repo = ctx.repo.clone();
+        let oid_obj = ObjectId::new(&oid);
+        async move {
+            let meta =
+                tokio::task::spawn_blocking(move || repo.commit_info(oid_obj))
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(CommitGql::from(meta))
+        }
+    })
+    .await
+}
+
+pub async fn resolve_commit_history(
+    ctx: &GraphqlContext,
+    limit: Option<i32>,
+    skip: Option<i32>,
+    sort: Option<String>,
+) -> anyhow::Result<Vec<CommitGql>> {
+    let revision = repo_revision(ctx).await;
+    let sort_str = sort.as_deref().unwrap_or("time");
+    let key_parts = format!(
+        "{}:{}:{}:{}",
+        limit.map(|l| l.to_string()).unwrap_or_default(),
+        skip.map(|s| s.to_string()).unwrap_or_default(),
+        sort_str,
+        revision,
+    );
+    let key = mutable_cache_key(
+        ctx,
+        "query:git:commit_history",
+        &[&key_parts],
+        &revision,
+    );
+    cached_json(&ctx.cache, &key, MUTABLE_TTL, || {
+        let repo = ctx.repo.clone();
+        let walk_sort = match sort_str {
+            "topological" => CommitWalkSort::Topological,
+            "time" => CommitWalkSort::Time,
+            "reverse" => CommitWalkSort::Reverse,
+            _ => CommitWalkSort::Time,
+        };
+        let params = CommitWalkParams {
+            limit: limit.map(|l| l as usize),
+            skip: skip.unwrap_or(0) as usize,
+            sort: walk_sort,
+            ..Default::default()
+        };
+        async move {
+            let commits = tokio::task::spawn_blocking(move || {
+                repo.commit_history(params)
+            })
+            .await?
+            .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(commits.into_iter().map(CommitGql::from).collect())
+        }
+    })
+    .await
+}
+
+pub async fn resolve_commit_summary(
+    ctx: &GraphqlContext,
+) -> anyhow::Result<CommitSummaryGql> {
+    let revision = repo_revision(ctx).await;
+    let key =
+        mutable_cache_key(ctx, "query:git:commit_summary", &[], &revision);
+    cached_json(&ctx.cache, &key, MUTABLE_TTL, || {
+        let repo = ctx.repo.clone();
+        async move {
+            let summary =
+                tokio::task::spawn_blocking(move || repo.commit_summary())
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(CommitSummaryGql::from(summary))
+        }
+    })
+    .await
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct CommitSummaryGql {
+    pub head: Option<CommitGql>,
+    pub count: i32,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl CommitSummaryGql {
+    fn head(&self) -> Option<&CommitGql> {
+        self.head.as_ref()
+    }
+    fn count(&self) -> i32 {
+        self.count
+    }
+}
+
+impl From<CommitSummary> for CommitSummaryGql {
+    fn from(s: CommitSummary) -> Self {
+        CommitSummaryGql {
+            head: s.head.map(CommitGql::from),
+            count: s.count as i32,
+        }
+    }
+}
diff --git a/lib/git/graphql/mod.rs b/lib/git/graphql/mod.rs
new file mode 100644
index 0000000..31892b1
--- /dev/null
+++ b/lib/git/graphql/mod.rs
@@ -0,0 +1,191 @@
+pub mod blob;
+pub mod branch;
+pub mod cache_helper;
+pub mod commit;
+pub mod tag;
+pub mod tree;
+
+use std::path::PathBuf;
+
+use actix_web::{HttpResponse, web};
+use cache::AppCache;
+use db::database::AppDatabase;
+use juniper::{
+    EmptyMutation, EmptySubscription, FieldResult, RootNode, graphql_object,
+};
+use serde_json::json;
+
+use crate::{
+    bare::GitBare,
+    graphql::{
+        blob::{BlobResult, resolve_blob, resolve_blob_size},
+        branch::{
+            BranchGql, BranchSummaryGql, resolve_branch,
+            resolve_branch_summary, resolve_branches, resolve_head_branch,
+        },
+        commit::{
+            CommitGql, CommitSummaryGql, resolve_commit,
+            resolve_commit_history, resolve_commit_summary,
+        },
+        tag::{
+            TagGql, TagSummaryGql, resolve_tag, resolve_tag_summary,
+            resolve_tags,
+        },
+        tree::{TreeEntryGql, TreeInfoGql, resolve_tree, resolve_tree_entries},
+    },
+};
+
+type Schema = RootNode<
+    GraphqlQuery,
+    EmptyMutation<GraphqlContext>,
+    EmptySubscription<GraphqlContext>,
+>;
+
+fn schema() -> Schema {
+    Schema::new(
+        GraphqlQuery,
+        EmptyMutation::<GraphqlContext>::new(),
+        EmptySubscription::<GraphqlContext>::new(),
+    )
+}
+
+pub async fn graphql_handle(
+    path: web::Path<(String, String)>,
+    state: web::Data<crate::http::HttpAppState>,
+    body: web::Json<juniper::http::GraphQLRequest>,
+) -> HttpResponse {
+    let (wk, repo_name) = path.into_inner();
+    let repo = match state.git_state.repo(wk, repo_name).await {
+        Ok(repo) => repo,
+        Err(err) => {
+            return HttpResponse::InternalServerError().json(json!({
+                "message": err.to_string()
+            }));
+        }
+    };
+
+    let ctx = GraphqlContext {
+        repo: GitBare {
+            bare_dir: PathBuf::from(&repo.repo.storage_path),
+        },
+        cache: state.git_state.cache.clone(),
+        db: state.git_state.db.clone(),
+    };
+
+    let schema = schema();
+    let response = body.execute(&schema, &ctx).await;
+
+    let status_code = if response.is_ok() { 200 } else { 400 };
+    HttpResponse::build(
+        actix_web::http::StatusCode::from_u16(status_code).unwrap(),
+    )
+    .content_type("application/json")
+    .json(response)
+}
+
+#[derive(Clone)]
+pub struct GraphqlContext {
+    pub repo: GitBare,
+    pub cache: AppCache,
+    pub db: AppDatabase,
+}
+
+impl juniper::Context for GraphqlContext {}
+
+pub struct GraphqlQuery;
+
+fn to_field_error(e: anyhow::Error) -> juniper::FieldError {
+    juniper::FieldError::new(e.to_string(), juniper::Value::null())
+}
+
+#[graphql_object]
+#[graphql(context = GraphqlContext)]
+impl GraphqlQuery {
+    fn api_version() -> &'static str {
+        env!("CARGO_PKG_VERSION")
+    }
+
+    async fn head_branch(ctx: &GraphqlContext) -> FieldResult<BranchGql> {
+        resolve_head_branch(ctx).await.map_err(to_field_error)
+    }
+
+    async fn branches(ctx: &GraphqlContext) -> FieldResult<Vec<BranchGql>> {
+        resolve_branches(ctx).await.map_err(to_field_error)
+    }
+
+    async fn branch(
+        ctx: &GraphqlContext,
+        name: String,
+    ) -> FieldResult<BranchGql> {
+        resolve_branch(ctx, name).await.map_err(to_field_error)
+    }
+
+    async fn branch_summary(
+        ctx: &GraphqlContext,
+    ) -> FieldResult<BranchSummaryGql> {
+        resolve_branch_summary(ctx).await.map_err(to_field_error)
+    }
+
+    async fn tags(ctx: &GraphqlContext) -> FieldResult<Vec<TagGql>> {
+        resolve_tags(ctx).await.map_err(to_field_error)
+    }
+
+    async fn tag(ctx: &GraphqlContext, name: String) -> FieldResult<TagGql> {
+        resolve_tag(ctx, name).await.map_err(to_field_error)
+    }
+
+    async fn tag_summary(ctx: &GraphqlContext) -> FieldResult<TagSummaryGql> {
+        resolve_tag_summary(ctx).await.map_err(to_field_error)
+    }
+
+    async fn commit(
+        ctx: &GraphqlContext,
+        oid: String,
+    ) -> FieldResult<CommitGql> {
+        resolve_commit(ctx, oid).await.map_err(to_field_error)
+    }
+
+    async fn commit_history(
+        ctx: &GraphqlContext,
+        limit: Option<i32>,
+        skip: Option<i32>,
+        sort: Option<String>,
+    ) -> FieldResult<Vec<CommitGql>> {
+        resolve_commit_history(ctx, limit, skip, sort)
+            .await
+            .map_err(to_field_error)
+    }
+
+    async fn commit_summary(
+        ctx: &GraphqlContext,
+    ) -> FieldResult<CommitSummaryGql> {
+        resolve_commit_summary(ctx).await.map_err(to_field_error)
+    }
+
+    async fn tree(
+        ctx: &GraphqlContext,
+        oid: String,
+    ) -> FieldResult<TreeInfoGql> {
+        resolve_tree(ctx, oid).await.map_err(to_field_error)
+    }
+
+    async fn tree_entries(
+        ctx: &GraphqlContext,
+        tree_oid: String,
+    ) -> FieldResult<Vec<TreeEntryGql>> {
+        resolve_tree_entries(ctx, tree_oid)
+            .await
+            .map_err(to_field_error)
+    }
+
+    async fn blob_size(ctx: &GraphqlContext, oid: String) -> FieldResult<i32> {
+        resolve_blob_size(ctx, oid).await.map_err(to_field_error)
+    }
+
+    async fn blob(
+        ctx: &GraphqlContext,
+        oid: String,
+    ) -> FieldResult<BlobResult> {
+        resolve_blob(ctx, oid).await.map_err(to_field_error)
+    }
+}
diff --git a/lib/git/graphql/tag.rs b/lib/git/graphql/tag.rs
new file mode 100644
index 0000000..1aa06c4
--- /dev/null
+++ b/lib/git/graphql/tag.rs
@@ -0,0 +1,139 @@
+use std::time::Duration;
+
+use juniper::graphql_object;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    cmd::tag::{TagItem, TagSummary},
+    graphql::{
+        GraphqlContext,
+        cache_helper::{
+            MUTABLE_TTL, cached_json, mutable_cache_key, repo_revision,
+        },
+    },
+};
+
+const TAG_TTL: Duration = MUTABLE_TTL;
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct TagGql {
+    pub name: String,
+    pub oid: String,
+    pub target: String,
+    pub is_annotated: bool,
+    pub message: Option<String>,
+    pub tagger: Option<String>,
+    pub tagger_email: Option<String>,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl TagGql {
+    fn name(&self) -> &str {
+        &self.name
+    }
+    fn oid(&self) -> &str {
+        &self.oid
+    }
+    fn target(&self) -> &str {
+        &self.target
+    }
+    fn is_annotated(&self) -> bool {
+        self.is_annotated
+    }
+    fn message(&self) -> Option<&str> {
+        self.message.as_deref()
+    }
+    fn tagger(&self) -> Option<&str> {
+        self.tagger.as_deref()
+    }
+    fn tagger_email(&self) -> Option<&str> {
+        self.tagger_email.as_deref()
+    }
+}
+
+impl From<TagItem> for TagGql {
+    fn from(item: TagItem) -> Self {
+        TagGql {
+            name: item.name,
+            oid: item.oid.0,
+            target: item.target.0,
+            is_annotated: item.is_annotated,
+            message: item.message,
+            tagger: item.tagger,
+            tagger_email: item.tagger_email,
+        }
+    }
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct TagSummaryGql {
+    pub total_count: i32,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl TagSummaryGql {
+    fn total_count(&self) -> i32 {
+        self.total_count
+    }
+}
+
+impl From<TagSummary> for TagSummaryGql {
+    fn from(s: TagSummary) -> Self {
+        TagSummaryGql {
+            total_count: s.total_count as i32,
+        }
+    }
+}
+
+pub async fn resolve_tags(ctx: &GraphqlContext) -> anyhow::Result<Vec<TagGql>> {
+    let revision = repo_revision(ctx).await;
+    let key = mutable_cache_key(ctx, "query:git:tags", &[], &revision);
+    cached_json(&ctx.cache, &key, TAG_TTL, || {
+        let repo = ctx.repo.clone();
+        async move {
+            let items = tokio::task::spawn_blocking(move || repo.tag_list())
+                .await?
+                .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(items.into_iter().map(TagGql::from).collect())
+        }
+    })
+    .await
+}
+
+pub async fn resolve_tag(
+    ctx: &GraphqlContext,
+    name: String,
+) -> anyhow::Result<TagGql> {
+    let revision = repo_revision(ctx).await;
+    let key = mutable_cache_key(ctx, "query:git:tag", &[&name], &revision);
+    cached_json(&ctx.cache, &key, TAG_TTL, || {
+        let repo = ctx.repo.clone();
+        let tag_name = name.clone();
+        async move {
+            let item =
+                tokio::task::spawn_blocking(move || repo.tag_info(tag_name))
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(TagGql::from(item))
+        }
+    })
+    .await
+}
+
+pub async fn resolve_tag_summary(
+    ctx: &GraphqlContext,
+) -> anyhow::Result<TagSummaryGql> {
+    let revision = repo_revision(ctx).await;
+    let key = mutable_cache_key(ctx, "query:git:tag_summary", &[], &revision);
+    cached_json(&ctx.cache, &key, TAG_TTL, || {
+        let repo = ctx.repo.clone();
+        async move {
+            let summary =
+                tokio::task::spawn_blocking(move || repo.tag_summary())
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(TagSummaryGql::from(summary))
+        }
+    })
+    .await
+}
diff --git a/lib/git/graphql/tree.rs b/lib/git/graphql/tree.rs
new file mode 100644
index 0000000..4fa0bac
--- /dev/null
+++ b/lib/git/graphql/tree.rs
@@ -0,0 +1,134 @@
+use std::time::Duration;
+
+use juniper::graphql_object;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    cmd::{
+        oid::ObjectId,
+        tree::{TreeEntry, TreeInfo, TreeKind},
+    },
+    graphql::{
+        GraphqlContext,
+        cache_helper::{IMMUTABLE_TTL, cache_key, cached_json},
+    },
+};
+
+const TREE_TTL: Duration = IMMUTABLE_TTL;
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct TreeInfoGql {
+    pub oid: String,
+    pub entry_count: i32,
+    pub is_empty: bool,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl TreeInfoGql {
+    fn oid(&self) -> &str {
+        &self.oid
+    }
+    fn entry_count(&self) -> i32 {
+        self.entry_count
+    }
+    fn is_empty(&self) -> bool {
+        self.is_empty
+    }
+}
+
+impl From<TreeInfo> for TreeInfoGql {
+    fn from(info: TreeInfo) -> Self {
+        TreeInfoGql {
+            oid: info.oid.0,
+            entry_count: info.entry_count as i32,
+            is_empty: info.is_empty,
+        }
+    }
+}
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct TreeEntryGql {
+    pub name: String,
+    pub oid: String,
+    pub kind: String,
+    pub filemode: i32,
+    pub is_binary: bool,
+    pub is_lfs: bool,
+}
+
+#[graphql_object(context = GraphqlContext)]
+impl TreeEntryGql {
+    fn name(&self) -> &str {
+        &self.name
+    }
+    fn oid(&self) -> &str {
+        &self.oid
+    }
+    fn kind(&self) -> &str {
+        &self.kind
+    }
+    fn filemode(&self) -> i32 {
+        self.filemode
+    }
+    fn is_binary(&self) -> bool {
+        self.is_binary
+    }
+    fn is_lfs(&self) -> bool {
+        self.is_lfs
+    }
+}
+
+impl From<TreeEntry> for TreeEntryGql {
+    fn from(entry: TreeEntry) -> Self {
+        TreeEntryGql {
+            name: entry.name,
+            oid: entry.oid.0,
+            kind: match entry.kind {
+                TreeKind::Blob => "blob".to_string(),
+                TreeKind::Tree => "tree".to_string(),
+                TreeKind::LfsPointer => "lfs_pointer".to_string(),
+            },
+            filemode: entry.filemode as i32,
+            is_binary: entry.is_binary,
+            is_lfs: entry.is_lfs,
+        }
+    }
+}
+
+pub async fn resolve_tree(
+    ctx: &GraphqlContext,
+    oid: String,
+) -> anyhow::Result<TreeInfoGql> {
+    let key = cache_key("query:git:tree", &[&oid]);
+    cached_json(&ctx.cache, &key, TREE_TTL, || {
+        let repo = ctx.repo.clone();
+        let oid_obj = ObjectId::new(&oid);
+        async move {
+            let info =
+                tokio::task::spawn_blocking(move || repo.resolve_tree(oid_obj))
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(TreeInfoGql::from(info))
+        }
+    })
+    .await
+}
+
+pub async fn resolve_tree_entries(
+    ctx: &GraphqlContext,
+    tree_oid: String,
+) -> anyhow::Result<Vec<TreeEntryGql>> {
+    let key = cache_key("query:git:tree_entries", &[&tree_oid]);
+    cached_json(&ctx.cache, &key, TREE_TTL, || {
+        let repo = ctx.repo.clone();
+        let oid_obj = ObjectId::new(&tree_oid);
+        async move {
+            let entries =
+                tokio::task::spawn_blocking(move || repo.tree_entries(oid_obj))
+                    .await?
+                    .map_err(|e| anyhow::anyhow!(e))?;
+            Ok(entries.into_iter().map(TreeEntryGql::from).collect())
+        }
+    })
+    .await
+}
diff --git a/lib/git/http/action.rs b/lib/git/http/action.rs
new file mode 100644
index 0000000..260403e
--- /dev/null
+++ b/lib/git/http/action.rs
@@ -0,0 +1,101 @@
+use actix_web::{HttpResponse, web};
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    http::{HttpAppState, utils::get_repo_model},
+    sync::cicheck::poll_ci_task_for_repo,
+};
+
+#[derive(Debug, Deserialize)]
+pub struct ActionQuery {
+    #[serde(default = "default_timeout")]
+    pub timeout: usize,
+}
+
+fn default_timeout() -> usize {
+    5
+}
+
+#[derive(Debug, Serialize)]
+struct ActionTask {
+    id: String,
+    repo_id: String,
+    pipeline_name: String,
+    trigger: String,
+}
+
+#[derive(Debug, Serialize)]
+struct ActionResponse {
+    status: String,
+    task: Option<ActionTask>,
+}
+pub async fn action_poll(
+    path: web::Path<(String, String)>,
+    query: web::Query<ActionQuery>,
+    state: web::Data<HttpAppState>,
+) -> HttpResponse {
+    let (namespace, repo_name) = path.into_inner();
+
+    let repo_model =
+        match get_repo_model(&namespace, &repo_name, &state.db).await {
+            Ok(m) => m,
+            Err(_) => {
+                return HttpResponse::NotFound().json(ActionResponse {
+                    status: "not_found".into(),
+                    task: None,
+                });
+            }
+        };
+
+    let task_json =
+        poll_ci_task_for_repo(&state.sync.pool(), repo_model.id, query.timeout)
+            .await;
+
+    match task_json {
+        Some(json) => {
+            let hook_task: serde_json::Value = match serde_json::from_str(&json)
+            {
+                Ok(v) => v,
+                Err(_) => {
+                    return HttpResponse::InternalServerError().json(
+                        ActionResponse {
+                            status: "error".into(),
+                            task: None,
+                        },
+                    );
+                }
+            };
+
+            let task_id = hook_task
+                .get("id")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+
+            let pipeline_name = hook_task
+                .get("payload")
+                .and_then(|p| p.get("pipeline_name"))
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+
+            let trigger = hook_task
+                .get("payload")
+                .and_then(|p| p.get("trigger"))
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+
+            HttpResponse::Ok().json(ActionResponse {
+                status: "pending".into(),
+                task: Some(ActionTask {
+                    id: task_id,
+                    repo_id: repo_model.id.to_string(),
+                    pipeline_name,
+                    trigger,
+                }),
+            })
+        }
+        None => HttpResponse::NoContent().finish(),
+    }
+}
diff --git a/lib/git/http/auth.rs b/lib/git/http/auth.rs
new file mode 100644
index 0000000..eebc07c
--- /dev/null
+++ b/lib/git/http/auth.rs
@@ -0,0 +1,94 @@
+use actix_web::{Error, HttpRequest};
+use argon2::{
+    Argon2,
+    password_hash::{PasswordHash, PasswordVerifier},
+};
+use db::database::AppDatabase;
+use model::{
+    repos::RepoModel,
+    users::{user::UserModel, user_token::UserTokenModel},
+};
+
+use crate::{
+    http::utils::extract_basic_credentials, ssh::authz::SshAuthService,
+};
+
+pub async fn verify_access_token(
+    db: &AppDatabase,
+    username: &str,
+    access_key: &str,
+) -> Result<UserModel, Error> {
+    let user = sqlx::query_as::<_, UserModel>(
+        "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+                last_sign_in_at, created_at, updated_at \
+         FROM \"user\" \
+         WHERE username = $1",
+    )
+    .bind(username)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorUnauthorized("Invalid username or access key"))?
+    .ok_or_else(|| actix_web::error::ErrorUnauthorized("Invalid username or access key"))?;
+
+    let tokens: Vec<UserTokenModel> = sqlx::query_as::<_, UserTokenModel>(
+        "SELECT id, \"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at \
+         FROM user_token \
+         WHERE \"user\" = $1 AND is_revoked = false",
+    )
+    .bind(user.id)
+    .fetch_all(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorUnauthorized("Invalid username or access key"))?
+    .into_iter()
+    .filter(|token| {
+        token
+            .expires_at
+            .map(|expires_at| expires_at >= chrono::Utc::now())
+            .unwrap_or(true)
+    })
+    .collect();
+
+    for token in tokens {
+        let Ok(hash) = PasswordHash::new(&token.token_hash) else {
+            tracing::warn!(
+                token_id = token.id,
+                "invalid stored access key hash"
+            );
+            continue;
+        };
+        if Argon2::default()
+            .verify_password(access_key.as_bytes(), &hash)
+            .is_ok()
+        {
+            return Ok(user);
+        }
+    }
+
+    Err(actix_web::error::ErrorUnauthorized(
+        "Invalid username or access key",
+    ))
+}
+
+pub async fn authorize_repo_access(
+    req: &HttpRequest,
+    db: &AppDatabase,
+    repo: &RepoModel,
+    is_write: bool,
+) -> Result<(), Error> {
+    if !is_write && repo.visibility == "public" {
+        return Ok(());
+    }
+
+    let (username, access_key) = extract_basic_credentials(req)?;
+    let user = verify_access_token(db, &username, &access_key).await?;
+    let authz = SshAuthService::new(db.clone());
+
+    let can_access = authz.check_repo_permission(&user, repo, is_write).await;
+    if !can_access {
+        return Err(actix_web::error::ErrorForbidden(
+            "No permission for repository",
+        ));
+    }
+
+    Ok(())
+}
diff --git a/lib/git/http/handler.rs b/lib/git/http/handler.rs
new file mode 100644
index 0000000..0c5c264
--- /dev/null
+++ b/lib/git/http/handler.rs
@@ -0,0 +1,327 @@
+use std::{
+    path::PathBuf,
+    pin::Pin,
+    time::{Duration, Instant},
+};
+
+use actix_web::{Error, HttpResponse, web};
+use async_stream::stream;
+use db::database::AppDatabase;
+use futures_util::{Stream, StreamExt};
+use model::repos::{RepoModel, repo_protect::RepoProtectModel};
+use tokio::io::AsyncWriteExt;
+
+use crate::ssh::{
+    branch_protect::check_branch_protection, ref_update::RefUpdate,
+};
+
+type ByteStream = Pin<Box<dyn Stream<Item = Result<Vec<u8>, std::io::Error>>>>;
+
+const PRE_PACK_LIMIT: usize = 1_048_576;
+const GIT_OPERATION_TIMEOUT: Duration = Duration::from_secs(30);
+
+pub fn is_valid_oid(oid: &str) -> bool {
+    oid.len() == 40 && oid.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+pub fn is_valid_lfs_oid(oid: &str) -> bool {
+    oid.len() == 64 && oid.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+pub struct GitHttpHandler {
+    storage_path: PathBuf,
+    repo: RepoModel,
+    db: AppDatabase,
+}
+
+impl GitHttpHandler {
+    pub fn new(
+        storage_path: PathBuf,
+        repo: RepoModel,
+        db: AppDatabase,
+    ) -> Self {
+        Self {
+            storage_path,
+            repo,
+            db,
+        }
+    }
+
+    pub async fn upload_pack(
+        &self,
+        payload: web::Payload,
+    ) -> Result<HttpResponse, Error> {
+        self.handle_git_rpc("upload-pack", payload).await
+    }
+
+    pub async fn receive_pack(
+        &self,
+        payload: web::Payload,
+    ) -> Result<HttpResponse, Error> {
+        self.handle_git_rpc("receive-pack", payload).await
+    }
+
+    pub async fn info_refs(
+        &self,
+        service: &str,
+    ) -> Result<HttpResponse, Error> {
+        let git_cmd = match service {
+            "git-upload-pack" => "upload-pack",
+            "git-receive-pack" => "receive-pack",
+            _ => {
+                return Err(actix_web::error::ErrorBadRequest(
+                    "Invalid service",
+                ));
+            }
+        };
+
+        let output = tokio::time::timeout(GIT_OPERATION_TIMEOUT, async {
+            tokio::process::Command::new("git")
+                .arg(git_cmd)
+                .arg("--stateless-rpc")
+                .arg("--advertise-refs")
+                .arg(&self.storage_path)
+                .output()
+                .await
+        })
+        .await
+        .map_err(|_| {
+            actix_web::error::ErrorInternalServerError("Git info-refs timeout")
+        })?
+        .map_err(|e| {
+            actix_web::error::ErrorInternalServerError(format!(
+                "Failed to execute git: {}",
+                e
+            ))
+        })?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            return Err(actix_web::error::ErrorInternalServerError(format!(
+                "Git command failed: {}",
+                stderr
+            )));
+        }
+
+        let mut response_body = Vec::new();
+        let header = format!("# service={}\n", service);
+        write_pkt_line(&mut response_body, header.as_bytes());
+        write_flush_pkt(&mut response_body);
+        response_body.extend_from_slice(&output.stdout);
+
+        Ok(HttpResponse::Ok()
+            .content_type(format!("application/x-{}-advertisement", service))
+            .insert_header(("Cache-Control", "no-cache"))
+            .body(response_body))
+    }
+
+    async fn handle_git_rpc(
+        &self,
+        service: &str,
+        mut payload: web::Payload,
+    ) -> Result<HttpResponse, Error> {
+        let started = Instant::now();
+        tracing::info!(
+            "git_rpc_started service={} repo={} repo_id={}",
+            service,
+            self.repo.name,
+            self.repo.id.to_string()
+        );
+        let mut child = tokio::process::Command::new("git")
+            .arg(service)
+            .arg("--stateless-rpc")
+            .arg(&self.storage_path)
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .kill_on_drop(true)
+            .spawn()
+            .map_err(|e| {
+                actix_web::error::ErrorInternalServerError(format!(
+                    "Failed to spawn git: {}",
+                    e
+                ))
+            })?;
+
+        let stream = stream! {
+            while let Some(chunk) = payload.next().await {
+                match chunk {
+                    Ok(bytes) => { yield Ok(bytes.to_vec()); }
+                    Err(e) => { yield Err(std::io::Error::new(std::io::ErrorKind::Other, e.to_string())); }
+                }
+            }
+        };
+        let mut stream: ByteStream = Box::pin(stream);
+
+        if service == "receive-pack" {
+            let branch_protects: Vec<RepoProtectModel> = sqlx::query_as::<_, RepoProtectModel>(
+                "SELECT id, repo, pattern, require_pull_request, required_approvals, \
+                        require_status_checks, required_status_contexts, enforce_admins, \
+                        allow_force_pushes, allow_deletions, created_at, updated_at \
+                 FROM repo_protect \
+                 WHERE repo = $1",
+            )
+            .bind(self.repo.id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| actix_web::error::ErrorInternalServerError(e.to_string()))?;
+
+            let mut pre_pack: Vec<u8> = Vec::with_capacity(65536);
+
+            while let Some(chunk) = stream.next().await {
+                let bytes = match chunk {
+                    Ok(b) => b,
+                    Err(e) => return Err(Error::from(e)),
+                };
+
+                if pre_pack.len() + bytes.len() > PRE_PACK_LIMIT {
+                    tracing::warn!(
+                        "git_rpc_payload_too_large service={} repo={} repo_id={}",
+                        service,
+                        self.repo.name,
+                        self.repo.id.to_string()
+                    );
+                    return Err(actix_web::error::ErrorPayloadTooLarge(
+                        format!(
+                            "Ref negotiation exceeds {} byte limit",
+                            PRE_PACK_LIMIT
+                        ),
+                    ));
+                }
+
+                if let Some(pos) = bytes.windows(4).position(|w| w == b"0000") {
+                    let end = pos + 4;
+                    pre_pack.extend_from_slice(&bytes[..end]);
+
+                    let refs = RefUpdate::parse_ref_updates(&pre_pack)
+                        .map_err(actix_web::error::ErrorBadRequest)?;
+                    if let Some(msg) = refs.iter().find_map(|r#ref| {
+                        check_branch_protection(&branch_protects, r#ref)
+                    }) {
+                        tracing::warn!(
+                            "branch_protection_violation repo={} repo_id={} message={}",
+                            self.repo.name,
+                            self.repo.id.to_string(),
+                            msg
+                        );
+                        return Err(actix_web::error::ErrorForbidden(msg));
+                    }
+
+                    let remaining: ByteStream = Box::pin(stream! {
+                        yield Ok(pre_pack);
+                        if end < bytes.len() {
+                            yield Ok(bytes[end..].to_vec());
+                        }
+                        while let Some(chunk) = stream.next().await {
+                            yield chunk;
+                        }
+                    });
+                    stream = remaining;
+                    break;
+                } else {
+                    pre_pack.extend_from_slice(&bytes);
+                }
+            }
+        }
+
+        if let Some(mut stdin) = child.stdin.take() {
+            let write_task = actix_web::rt::spawn(async move {
+                while let Some(chunk) = stream.next().await {
+                    match chunk {
+                        Ok(bytes) => {
+                            if let Err(e) = stdin.write_all(&bytes).await {
+                                return Err(e);
+                            }
+                        }
+                        Err(e) => {
+                            return Err(std::io::Error::new(
+                                std::io::ErrorKind::Other,
+                                e,
+                            ));
+                        }
+                    }
+                }
+                drop(stdin);
+                Ok::<_, std::io::Error>(())
+            });
+
+            let write_result =
+                tokio::time::timeout(GIT_OPERATION_TIMEOUT, write_task)
+                    .await
+                    .map_err(|_| {
+                        actix_web::error::ErrorInternalServerError(
+                            "Git stdin write timeout",
+                        )
+                    })?
+                    .map_err(|e| {
+                        actix_web::error::ErrorInternalServerError(format!(
+                            "Write error: {}",
+                            e
+                        ))
+                    })?;
+
+            if let Err(e) = write_result {
+                return Err(actix_web::error::ErrorInternalServerError(
+                    format!("Failed to write to git: {}", e),
+                ));
+            }
+        }
+
+        let output = tokio::time::timeout(
+            GIT_OPERATION_TIMEOUT,
+            child.wait_with_output(),
+        )
+        .await
+        .map_err(|_| {
+            actix_web::error::ErrorInternalServerError("Git operation timeout")
+        })?
+        .map_err(|e| {
+            actix_web::error::ErrorInternalServerError(format!(
+                "Git wait failed: {}",
+                e
+            ))
+        })?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            let ms = started.elapsed().as_millis() as u64;
+            tracing::error!(
+                "git_rpc_failed service={} repo={} repo_id={} duration_ms={} stderr={}",
+                service,
+                self.repo.name,
+                self.repo.id.to_string(),
+                ms,
+                stderr.to_string()
+            );
+            return Err(actix_web::error::ErrorInternalServerError(format!(
+                "Git command failed: {}",
+                stderr
+            )));
+        }
+
+        let ms = started.elapsed().as_millis() as u64;
+        tracing::info!(
+            "git_rpc_completed service={} repo={} repo_id={} duration_ms={} bytes_out={}",
+            service,
+            self.repo.name,
+            self.repo.id.to_string(),
+            ms,
+            output.stdout.len()
+        );
+
+        Ok(HttpResponse::Ok()
+            .content_type(format!("application/x-git-{}-result", service))
+            .insert_header(("Cache-Control", "no-cache"))
+            .body(output.stdout))
+    }
+}
+
+fn write_pkt_line(buf: &mut Vec<u8>, data: &[u8]) {
+    let len = data.len() + 4;
+    buf.extend_from_slice(format!("{:04x}", len).as_bytes());
+    buf.extend_from_slice(data);
+}
+
+fn write_flush_pkt(buf: &mut Vec<u8>) {
+    buf.extend_from_slice(b"0000");
+}
diff --git a/lib/git/http/lfs.rs b/lib/git/http/lfs.rs
new file mode 100644
index 0000000..e77c407
--- /dev/null
+++ b/lib/git/http/lfs.rs
@@ -0,0 +1,726 @@
+use std::{collections::HashMap, path::PathBuf};
+
+use actix_web::{HttpResponse, web};
+use cache::AppCache;
+use db::database::AppDatabase;
+use model::repos::{
+    RepoModel, repo_lfs_lock::RepoLfsLockModel,
+    repo_lfs_object::RepoLfsObjectModel,
+};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::{errors::GitError, http::handler::is_valid_lfs_oid};
+
+const LFS_AUTH_TOKEN_EXPIRY: u64 = 3600;
+const LFS_MAX_OBJECT_SIZE: i64 = 50 * 1024 * 1024 * 1024;
+
+#[derive(Deserialize, Serialize)]
+pub struct BatchRequest {
+    pub operation: String,
+    pub objects: Vec<LfsObjectReq>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transfers: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub r#ref: Option<LfsRef>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hash_algo: Option<String>,
+}
+
+#[derive(Deserialize, Serialize)]
+pub struct LfsRef {
+    pub name: String,
+}
+
+#[derive(Deserialize, Serialize, Clone)]
+pub struct LfsObjectReq {
+    pub oid: String,
+    pub size: i64,
+}
+
+#[derive(Serialize)]
+pub struct BatchResponse {
+    pub transfer: String,
+    pub objects: Vec<LfsObjectResponse>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hash_algo: Option<String>,
+}
+
+#[derive(Serialize)]
+pub struct LfsObjectResponse {
+    pub oid: String,
+    pub size: i64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub authenticated: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub actions: Option<HashMap<String, LfsAction>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<LfsError>,
+}
+
+#[derive(Serialize)]
+pub struct LfsAction {
+    pub href: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub header: Option<HashMap<String, String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_in: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_at: Option<String>,
+}
+
+#[derive(Serialize)]
+pub struct LfsError {
+    pub code: i32,
+    pub message: String,
+}
+
+#[derive(Deserialize)]
+pub struct CreateLockRequest {
+    pub oid: String,
+}
+
+#[derive(Serialize)]
+pub struct LockResponse {
+    pub id: Uuid,
+    pub path: String,
+    pub locked_by: Uuid,
+    pub locked_at: String,
+}
+
+pub struct LfsHandler {
+    pub storage_path: PathBuf,
+    pub model: RepoModel,
+    pub namespace: String,
+    pub db: AppDatabase,
+}
+
+impl LfsHandler {
+    pub fn new(
+        storage_path: PathBuf,
+        model: RepoModel,
+        namespace: String,
+        db: AppDatabase,
+    ) -> Self {
+        Self {
+            storage_path,
+            model,
+            namespace,
+            db,
+        }
+    }
+
+    fn get_lfs_storage_path(&self) -> PathBuf {
+        self.storage_path.join(".lfs")
+    }
+
+    fn get_object_path(&self, oid: &str) -> PathBuf {
+        let prefix = &oid[..2];
+        self.get_lfs_storage_path()
+            .join("objects")
+            .join(prefix)
+            .join(oid)
+    }
+
+    fn build_object_url(&self, base_url: &str, oid: &str) -> String {
+        format!(
+            "{}/{}/{}.git/info/lfs/objects/{}",
+            base_url, self.namespace, self.model.name, oid
+        )
+    }
+
+    pub async fn batch(
+        &self,
+        req: BatchRequest,
+        base_url: &str,
+    ) -> Result<BatchResponse, GitError> {
+        let operation = req.operation.as_str();
+
+        if operation != "upload" && operation != "download" {
+            return Err(GitError::InvalidOid(format!(
+                "Invalid operation: {}",
+                operation
+            )));
+        }
+
+        for obj in &req.objects {
+            if obj.size > LFS_MAX_OBJECT_SIZE {
+                return Err(GitError::InvalidOid(format!(
+                    "Object size {} exceeds maximum allowed size {}",
+                    obj.size, LFS_MAX_OBJECT_SIZE
+                )));
+            }
+        }
+
+        let oids: Vec<String> =
+            req.objects.iter().map(|o| o.oid.clone()).collect();
+
+        let existing: Vec<RepoLfsObjectModel> =
+            sqlx::query_as::<_, RepoLfsObjectModel>(
+                "SELECT repo, oid, size_bytes, storage_key, created_at \
+             FROM repo_lfs_object \
+             WHERE oid = ANY($1) AND repo = $2",
+            )
+            .bind(&oids)
+            .bind(self.model.id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        let existing_map: HashMap<&str, &RepoLfsObjectModel> =
+            existing.iter().map(|m| (m.oid.as_str(), m)).collect();
+
+        let mut response_objects = Vec::with_capacity(req.objects.len());
+
+        for obj in req.objects {
+            let existing = existing_map.get(obj.oid.as_str());
+
+            let mut actions = HashMap::new();
+
+            match operation {
+                "upload" => {
+                    if existing.is_none() {
+                        let upload_url =
+                            self.build_object_url(base_url, &obj.oid);
+
+                        let token = Uuid::now_v7().to_string();
+                        let mut headers = HashMap::new();
+                        headers.insert(
+                            "authorization".to_string(),
+                            format!("Bearer {}", token),
+                        );
+
+                        actions.insert(
+                            "upload".to_string(),
+                            LfsAction {
+                                href: upload_url,
+                                header: Some(headers),
+                                expires_in: Some(LFS_AUTH_TOKEN_EXPIRY as i64),
+                                expires_at: None,
+                            },
+                        );
+                    }
+                }
+                "download" => match existing {
+                    Some(_) => {
+                        let download_url =
+                            self.build_object_url(base_url, &obj.oid);
+
+                        let token = Uuid::now_v7().to_string();
+                        let mut headers = HashMap::new();
+                        headers.insert(
+                            "authorization".to_string(),
+                            format!("Bearer {}", token),
+                        );
+
+                        actions.insert(
+                            "download".to_string(),
+                            LfsAction {
+                                href: download_url,
+                                header: Some(headers),
+                                expires_in: Some(LFS_AUTH_TOKEN_EXPIRY as i64),
+                                expires_at: None,
+                            },
+                        );
+                    }
+                    None => {
+                        response_objects.push(LfsObjectResponse {
+                            oid: obj.oid,
+                            size: obj.size,
+                            authenticated: None,
+                            actions: None,
+                            error: Some(LfsError {
+                                code: 404,
+                                message: "Object does not exist".to_string(),
+                            }),
+                        });
+                        continue;
+                    }
+                },
+                _ => {}
+            }
+
+            response_objects.push(LfsObjectResponse {
+                oid: obj.oid,
+                size: obj.size,
+                authenticated: Some(true),
+                actions: if actions.is_empty() {
+                    None
+                } else {
+                    Some(actions)
+                },
+                error: None,
+            });
+        }
+
+        Ok(BatchResponse {
+            transfer: "basic".to_string(),
+            objects: response_objects,
+            hash_algo: req.hash_algo,
+        })
+    }
+
+    pub async fn batch_with_auth(
+        &self,
+        req: BatchRequest,
+        base_url: &str,
+        user_id: uuid::Uuid,
+        cache: &AppCache,
+    ) -> Result<BatchResponse, GitError> {
+        let operation = req.operation.as_str();
+
+        if operation != "upload" && operation != "download" {
+            return Err(GitError::InvalidOid(format!(
+                "Invalid operation: {}",
+                operation
+            )));
+        }
+
+        for obj in &req.objects {
+            if obj.size > LFS_MAX_OBJECT_SIZE {
+                return Err(GitError::InvalidOid(format!(
+                    "Object size {} exceeds maximum allowed size {}",
+                    obj.size, LFS_MAX_OBJECT_SIZE
+                )));
+            }
+        }
+
+        let oids: Vec<String> =
+            req.objects.iter().map(|o| o.oid.clone()).collect();
+
+        let existing: Vec<RepoLfsObjectModel> =
+            sqlx::query_as::<_, RepoLfsObjectModel>(
+                "SELECT repo, oid, size_bytes, storage_key, created_at \
+             FROM repo_lfs_object \
+             WHERE oid = ANY($1) AND repo = $2",
+            )
+            .bind(&oids)
+            .bind(self.model.id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        let existing_map: HashMap<&str, &RepoLfsObjectModel> =
+            existing.iter().map(|m| (m.oid.as_str(), m)).collect();
+
+        let mut response_objects = Vec::with_capacity(req.objects.len());
+
+        for obj in req.objects {
+            let existing = existing_map.get(obj.oid.as_str());
+
+            let mut actions = HashMap::new();
+
+            match operation {
+                "upload" => {
+                    if existing.is_none() {
+                        let upload_url =
+                            self.build_object_url(base_url, &obj.oid);
+
+                        let token = Uuid::now_v7().to_string();
+                        crate::http::lfs_routes::store_lfs_token(
+                            cache,
+                            &token,
+                            self.model.id,
+                            user_id,
+                            "upload",
+                        )
+                        .await;
+
+                        let mut headers = HashMap::new();
+                        headers.insert(
+                            "authorization".to_string(),
+                            format!("Bearer {}", token),
+                        );
+
+                        actions.insert(
+                            "upload".to_string(),
+                            LfsAction {
+                                href: upload_url,
+                                header: Some(headers),
+                                expires_in: Some(LFS_AUTH_TOKEN_EXPIRY as i64),
+                                expires_at: None,
+                            },
+                        );
+                    }
+                }
+                "download" => match existing {
+                    Some(_) => {
+                        let download_url =
+                            self.build_object_url(base_url, &obj.oid);
+
+                        let token = Uuid::now_v7().to_string();
+                        crate::http::lfs_routes::store_lfs_token(
+                            cache,
+                            &token,
+                            self.model.id,
+                            user_id,
+                            "download",
+                        )
+                        .await;
+
+                        let mut headers = HashMap::new();
+                        headers.insert(
+                            "authorization".to_string(),
+                            format!("Bearer {}", token),
+                        );
+
+                        actions.insert(
+                            "download".to_string(),
+                            LfsAction {
+                                href: download_url,
+                                header: Some(headers),
+                                expires_in: Some(LFS_AUTH_TOKEN_EXPIRY as i64),
+                                expires_at: None,
+                            },
+                        );
+                    }
+                    None => {
+                        response_objects.push(LfsObjectResponse {
+                            oid: obj.oid,
+                            size: obj.size,
+                            authenticated: None,
+                            actions: None,
+                            error: Some(LfsError {
+                                code: 404,
+                                message: "Object does not exist".to_string(),
+                            }),
+                        });
+                        continue;
+                    }
+                },
+                _ => {}
+            }
+
+            response_objects.push(LfsObjectResponse {
+                oid: obj.oid,
+                size: obj.size,
+                authenticated: Some(true),
+                actions: if actions.is_empty() {
+                    None
+                } else {
+                    Some(actions)
+                },
+                error: None,
+            });
+        }
+
+        Ok(BatchResponse {
+            transfer: "basic".to_string(),
+            objects: response_objects,
+            hash_algo: req.hash_algo,
+        })
+    }
+
+    pub async fn upload_object(
+        &self,
+        oid: &str,
+        payload: web::Payload,
+    ) -> Result<HttpResponse, GitError> {
+        if !is_valid_lfs_oid(oid) {
+            return Err(GitError::InvalidOid(format!(
+                "Invalid OID format: {}",
+                oid
+            )));
+        }
+
+        let object_path = self.get_object_path(oid);
+        if let Some(parent) = object_path.parent() {
+            tokio::fs::create_dir_all(parent).await.map_err(|e| {
+                GitError::Internal(format!("Failed to create directory: {}", e))
+            })?;
+        }
+
+        let temp_path = object_path.with_extension("tmp");
+        let mut file =
+            tokio::fs::File::create(&temp_path).await.map_err(|e| {
+                GitError::Internal(format!("Failed to create temp file: {}", e))
+            })?;
+
+        use futures_util::stream::StreamExt;
+        use sha2::Digest;
+        use tokio::io::AsyncWriteExt;
+
+        let mut payload = payload;
+        let mut size = 0i64;
+        let mut hasher = sha2::Sha256::new();
+
+        while let Some(chunk) = payload.next().await {
+            let chunk = chunk.map_err(|e| {
+                GitError::Internal(format!("Payload error: {}", e))
+            })?;
+            size += chunk.len() as i64;
+            if size > LFS_MAX_OBJECT_SIZE {
+                let _ = tokio::fs::remove_file(&temp_path).await;
+                return Err(GitError::InvalidOid(format!(
+                    "Object size exceeds maximum allowed size {}",
+                    LFS_MAX_OBJECT_SIZE
+                )));
+            }
+            hasher.update(&chunk);
+            if let Err(e) = file.write_all(&chunk).await {
+                let _ = tokio::fs::remove_file(&temp_path).await;
+                return Err(GitError::Internal(format!(
+                    "Failed to write file: {}",
+                    e
+                )));
+            }
+        }
+
+        file.flush().await.map_err(|e| {
+            GitError::Internal(format!("Failed to flush file: {}", e))
+        })?;
+        drop(file);
+
+        let hash_bytes = hasher.finalize();
+        let calculated_oid = hex::encode(hash_bytes.as_slice());
+
+        if calculated_oid != oid {
+            let _ = tokio::fs::remove_file(&temp_path).await;
+            return Err(GitError::InvalidOid(format!(
+                "OID mismatch: expected {}, got {}",
+                oid, calculated_oid
+            )));
+        }
+
+        if let Err(e) = tokio::fs::rename(&temp_path, &object_path).await {
+            let _ = tokio::fs::remove_file(&temp_path).await;
+            return Err(GitError::Internal(format!(
+                "Failed to move file: {}",
+                e
+            )));
+        }
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO repo_lfs_object (repo, oid, size_bytes, storage_key, created_at) \
+             VALUES ($1, $2, $3, $4, $5)",
+        )
+        .bind(self.model.id)
+        .bind(oid)
+        .bind(size)
+        .bind(object_path.to_string_lossy().to_string())
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        Ok(HttpResponse::Ok().finish())
+    }
+
+    pub async fn download_object(
+        &self,
+        oid: &str,
+    ) -> Result<HttpResponse, GitError> {
+        if !is_valid_lfs_oid(oid) {
+            return Err(GitError::InvalidOid(format!(
+                "Invalid OID format: {}",
+                oid
+            )));
+        }
+
+        let obj = sqlx::query_as::<_, RepoLfsObjectModel>(
+            "SELECT repo, oid, size_bytes, storage_key, created_at \
+             FROM repo_lfs_object \
+             WHERE oid = $1 AND repo = $2",
+        )
+        .bind(oid)
+        .bind(self.model.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?
+        .ok_or_else(|| GitError::NotFound("Object not found".to_string()))?;
+
+        let expected_base = self.get_lfs_storage_path();
+        let obj_path = PathBuf::from(&obj.storage_key);
+        if !obj_path.starts_with(&expected_base) {
+            tracing::error!(
+                "LFS object path outside storage directory: {}",
+                obj.storage_key
+            );
+            return Err(GitError::AuthFailed(
+                "Invalid object path".to_string(),
+            ));
+        }
+
+        let file = tokio::fs::File::open(&obj_path).await.map_err(|e| {
+            GitError::Internal(format!("Failed to open file: {}", e))
+        })?;
+
+        use actix_web::body::BodyStream;
+        use futures_util::stream;
+        use tokio::io::AsyncReadExt;
+
+        let chunk_size: usize = 65536;
+
+        let stream = stream::unfold(file, move |mut file| async move {
+            let mut buffer = vec![0u8; chunk_size];
+            match file.read(&mut buffer).await {
+                Ok(0) => None,
+                Ok(n) => {
+                    buffer.truncate(n);
+                    Some((
+                        Ok::<_, std::io::Error>(actix_web::web::Bytes::from(
+                            buffer,
+                        )),
+                        file,
+                    ))
+                }
+                Err(e) => Some((Err(e), file)),
+            }
+        });
+
+        Ok(HttpResponse::Ok()
+            .content_type("application/octet-stream")
+            .insert_header(("Content-Length", obj.size_bytes.to_string()))
+            .body(BodyStream::new(stream)))
+    }
+
+    pub async fn lock_object(
+        &self,
+        oid: &str,
+        user_id: uuid::Uuid,
+    ) -> Result<LockResponse, GitError> {
+        if !is_valid_lfs_oid(oid) {
+            return Err(GitError::InvalidOid(format!(
+                "Invalid OID format: {}",
+                oid
+            )));
+        }
+
+        let now = chrono::Utc::now();
+        let lock_id = Uuid::now_v7();
+
+        let result = sqlx::query(
+            "INSERT INTO repo_lfs_lock (id, repo, path, locked_by, ref_name, created_at) \
+             VALUES ($1, $2, $3, $4, NULL, $5)",
+        )
+        .bind(lock_id)
+        .bind(self.model.id)
+        .bind(oid)
+        .bind(user_id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await;
+
+        match result {
+            Ok(_) => Ok(LockResponse {
+                id: lock_id,
+                path: oid.to_string(),
+                locked_by: user_id,
+                locked_at: now.to_rfc3339(),
+            }),
+            Err(e) => {
+                let err_msg = format!("{}", e);
+                if err_msg.contains("duplicate key")
+                    || err_msg.contains("23505")
+                {
+                    return Err(GitError::Locked("Already locked".to_string()));
+                }
+                Err(GitError::Internal(format!("DB error: {}", e)))
+            }
+        }
+    }
+
+    pub async fn unlock_object(
+        &self,
+        lock_id: &str,
+        user_id: uuid::Uuid,
+    ) -> Result<(), GitError> {
+        let lock_uuid = Uuid::parse_str(lock_id)
+            .map_err(|_| GitError::NotFound("Invalid lock ID".to_string()))?;
+
+        let existing = sqlx::query_as::<_, RepoLfsLockModel>(
+            "SELECT id, repo, path, locked_by, ref_name, created_at \
+             FROM repo_lfs_lock \
+             WHERE id = $1 AND repo = $2",
+        )
+        .bind(lock_uuid)
+        .bind(self.model.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?
+        .ok_or_else(|| GitError::NotFound("Lock not found".to_string()))?;
+
+        if existing.locked_by != user_id
+            && existing.locked_by != self.model.created_by
+        {
+            return Err(GitError::PermissionDenied(
+                "Not allowed to unlock".to_string(),
+            ));
+        }
+
+        sqlx::query("DELETE FROM repo_lfs_lock WHERE id = $1 AND repo = $2")
+            .bind(lock_uuid)
+            .bind(self.model.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn list_locks(
+        &self,
+        maybe_oid: Option<&str>,
+    ) -> Result<Vec<LockResponse>, GitError> {
+        let rows: Vec<RepoLfsLockModel> = if let Some(oid) = maybe_oid {
+            sqlx::query_as::<_, RepoLfsLockModel>(
+                "SELECT id, repo, path, locked_by, ref_name, created_at \
+                 FROM repo_lfs_lock \
+                 WHERE repo = $1 AND path = $2",
+            )
+            .bind(self.model.id)
+            .bind(oid)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?
+        } else {
+            sqlx::query_as::<_, RepoLfsLockModel>(
+                "SELECT id, repo, path, locked_by, ref_name, created_at \
+                 FROM repo_lfs_lock \
+                 WHERE repo = $1",
+            )
+            .bind(self.model.id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?
+        };
+
+        Ok(rows
+            .into_iter()
+            .map(|r| LockResponse {
+                id: r.id,
+                path: r.path,
+                locked_by: r.locked_by,
+                locked_at: r.created_at.to_rfc3339(),
+            })
+            .collect())
+    }
+
+    pub async fn get_lock(
+        &self,
+        lock_id: &str,
+    ) -> Result<LockResponse, GitError> {
+        let lock_uuid = Uuid::parse_str(lock_id)
+            .map_err(|_| GitError::NotFound("Invalid lock ID".to_string()))?;
+
+        let r = sqlx::query_as::<_, RepoLfsLockModel>(
+            "SELECT id, repo, path, locked_by, ref_name, created_at \
+             FROM repo_lfs_lock \
+             WHERE id = $1 AND repo = $2",
+        )
+        .bind(lock_uuid)
+        .bind(self.model.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?
+        .ok_or_else(|| GitError::NotFound("Lock not found".to_string()))?;
+
+        Ok(LockResponse {
+            id: r.id,
+            path: r.path,
+            locked_by: r.locked_by,
+            locked_at: r.created_at.to_rfc3339(),
+        })
+    }
+}
diff --git a/lib/git/http/lfs_routes.rs b/lib/git/http/lfs_routes.rs
new file mode 100644
index 0000000..2671883
--- /dev/null
+++ b/lib/git/http/lfs_routes.rs
@@ -0,0 +1,550 @@
+use std::path::PathBuf;
+
+use actix_web::{Error, HttpRequest, HttpResponse, web};
+use argon2::{
+    Argon2,
+    password_hash::{PasswordHash, PasswordVerifier},
+};
+use model::{
+    repos::RepoModel,
+    users::{user::UserModel, user_token::UserTokenModel},
+};
+
+use crate::{
+    errors::GitError,
+    http::{
+        HttpAppState,
+        auth::{authorize_repo_access, verify_access_token},
+        handler::is_valid_lfs_oid,
+        lfs::{BatchRequest, CreateLockRequest, LfsHandler},
+        utils::{extract_basic_credentials, get_repo_model},
+    },
+    ssh::authz::SshAuthService,
+    sync::push_queue::{
+        PushQueueEvent, PushQueueLease, PushQueueWaitError,
+        wait_for_push_queue_slot,
+    },
+};
+
+fn base_url(req: &HttpRequest) -> String {
+    let conn_info = req.connection_info();
+    format!("{}://{}", conn_info.scheme(), conn_info.host())
+}
+
+fn bearer_token(req: &HttpRequest) -> Result<String, Error> {
+    let auth_header = req
+        .headers()
+        .get("authorization")
+        .ok_or_else(|| {
+            actix_web::error::ErrorUnauthorized("Missing authorization header")
+        })?
+        .to_str()
+        .map_err(|_| {
+            actix_web::error::ErrorUnauthorized("Invalid authorization header")
+        })?;
+
+    if let Some(token) = auth_header.strip_prefix("Bearer ") {
+        Ok(token.to_string())
+    } else {
+        Err(actix_web::error::ErrorUnauthorized(
+            "Invalid authorization format",
+        ))
+    }
+}
+
+async fn user_uid(
+    req: &HttpRequest,
+    db: &db::database::AppDatabase,
+) -> Result<uuid::Uuid, Error> {
+    if let Ok((username, access_key)) = extract_basic_credentials(req) {
+        return verify_access_token(db, &username, &access_key)
+            .await
+            .map(|user| user.id);
+    }
+
+    let token = bearer_token(req)?;
+    find_user_by_bearer_token(&token, db).await
+}
+pub async fn store_lfs_token(
+    cache: &cache::AppCache,
+    token: &str,
+    repo_id: uuid::Uuid,
+    user_uid: uuid::Uuid,
+    operation: &str,
+) {
+    if let Some(mut conn) = cache.conn() {
+        use redis::AsyncCommands;
+        let value = format!("{}:{}:{}", repo_id, user_uid, operation);
+        let _: () = conn
+            .set_ex(format!("lfs:token:{}", token), value, 3600_u64)
+            .await
+            .map_err(
+                |e| tracing::warn!(error = %e, "failed to store lfs token"),
+            )
+            .unwrap_or(());
+    }
+}
+
+async fn validate_lfs_token(
+    token: &str,
+    cache: &cache::AppCache,
+    db: &db::database::AppDatabase,
+    expected_repo_id: uuid::Uuid,
+    expected_operation: &str,
+) -> Result<uuid::Uuid, Error> {
+    if let Some(mut conn) = cache.conn() {
+        use redis::AsyncCommands;
+        let stored: Option<String> = conn
+            .get::<String, String>(format!("lfs:token:{}", token))
+            .await
+            .ok();
+        if let Some(value) = stored {
+            let parts: Vec<&str> = value.split(':').collect();
+            if parts.len() == 3 {
+                let repo_id =
+                    uuid::Uuid::parse_str(parts[0]).map_err(|_| {
+                        actix_web::error::ErrorUnauthorized(
+                            "Invalid batch token",
+                        )
+                    })?;
+                let user_uid =
+                    uuid::Uuid::parse_str(parts[1]).map_err(|_| {
+                        actix_web::error::ErrorUnauthorized(
+                            "Invalid batch token",
+                        )
+                    })?;
+                let operation = parts[2];
+
+                if repo_id != expected_repo_id {
+                    return Err(actix_web::error::ErrorUnauthorized(
+                        "Token not valid for this repo",
+                    ));
+                }
+                if operation != expected_operation {
+                    return Err(actix_web::error::ErrorUnauthorized(
+                        "Token not valid for this operation",
+                    ));
+                }
+
+                let _: Result<(), redis::RedisError> =
+                    conn.del(format!("lfs:token:{}", token)).await;
+
+                return Ok(user_uid);
+            }
+        }
+    }
+
+    find_user_by_bearer_token(token, db).await
+}
+
+async fn find_user_by_bearer_token(
+    token: &str,
+    db: &db::database::AppDatabase,
+) -> Result<uuid::Uuid, Error> {
+    let tokens: Vec<UserTokenModel> = sqlx::query_as::<_, UserTokenModel>(
+        "SELECT id, \"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at \
+         FROM user_token \
+         WHERE is_revoked = false",
+    )
+    .fetch_all(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorUnauthorized("Authentication failed"))?;
+
+    for token_model in tokens {
+        if token_model
+            .expires_at
+            .map(|expires_at| expires_at < chrono::Utc::now())
+            .unwrap_or(false)
+        {
+            continue;
+        }
+
+        let Ok(hash) = PasswordHash::new(&token_model.token_hash) else {
+            tracing::warn!(
+                token_id = token_model.id,
+                "invalid stored bearer token hash"
+            );
+            continue;
+        };
+        if Argon2::default()
+            .verify_password(token.as_bytes(), &hash)
+            .is_ok()
+        {
+            return Ok(token_model.user);
+        }
+    }
+
+    Err(actix_web::error::ErrorUnauthorized("Invalid token"))
+}
+
+async fn authorize_user_repo_access(
+    db: &db::database::AppDatabase,
+    user_uid: uuid::Uuid,
+    repo: &RepoModel,
+    is_write: bool,
+) -> Result<(), Error> {
+    let user = sqlx::query_as::<_, UserModel>(
+        "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+                last_sign_in_at, created_at, updated_at \
+         FROM \"user\" \
+         WHERE id = $1",
+    )
+    .bind(user_uid)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorUnauthorized("Authentication failed"))?
+    .ok_or_else(|| actix_web::error::ErrorUnauthorized("Invalid token user"))?;
+
+    let authz = SshAuthService::new(db.clone());
+    if authz.check_repo_permission(&user, repo, is_write).await {
+        Ok(())
+    } else {
+        Err(actix_web::error::ErrorForbidden(
+            "No permission for repository",
+        ))
+    }
+}
+
+async fn acquire_lfs_write_queue(
+    state: &HttpAppState,
+    repo: &RepoModel,
+    operation: &'static str,
+) -> Result<PushQueueLease, Error> {
+    match wait_for_push_queue_slot(
+        state.sync.clone(),
+        repo.id,
+        |event, request_id| {
+            let request_id = request_id.to_string();
+            match event {
+                PushQueueEvent::Waiting(position) => {
+                    tracing::info!(
+                        repo = %repo.name,
+                        repo_id = %repo.id,
+                        request_id = %request_id,
+                        operation = operation,
+                        position = position.position,
+                        total = position.total,
+                        "lfs_write_queue_waiting"
+                    );
+                }
+                PushQueueEvent::Acquired => {
+                    tracing::info!(
+                        repo = %repo.name,
+                        repo_id = %repo.id,
+                        request_id = %request_id,
+                        operation = operation,
+                        "lfs_write_queue_acquired"
+                    );
+                }
+            }
+        },
+    )
+    .await
+    {
+        Ok(lease) => Ok(lease),
+        Err(PushQueueWaitError::Join(e)) => {
+            tracing::error!(
+                error = %e,
+                repo = %repo.name,
+                repo_id = %repo.id,
+                operation = operation,
+                "lfs_write_queue_join_failed"
+            );
+            Err(actix_web::error::ErrorServiceUnavailable(
+                "LFS write queue is temporarily unavailable. Please retry later.",
+            ))
+        }
+        Err(PushQueueWaitError::Lock(e)) => {
+            tracing::error!(
+                error = %e,
+                repo = %repo.name,
+                repo_id = %repo.id,
+                operation = operation,
+                "lfs_write_queue_lock_failed"
+            );
+            Err(actix_web::error::ErrorServiceUnavailable(
+                "LFS write queue lock failed. Please retry later.",
+            ))
+        }
+        Err(PushQueueWaitError::Timeout) => {
+            tracing::warn!(
+                repo = %repo.name,
+                repo_id = %repo.id,
+                operation = operation,
+                "lfs_write_queue_timeout"
+            );
+            Err(actix_web::error::ErrorServiceUnavailable(
+                "LFS write queue timed out. Please retry in a moment.",
+            ))
+        }
+    }
+}
+
+pub async fn lfs_batch(
+    req: HttpRequest,
+    path: web::Path<(String, String)>,
+    body: web::Json<BatchRequest>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name) = path.into_inner();
+    let batch_req = body.into_inner();
+    let is_write = batch_req.operation == "upload";
+
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+
+    if repo.visibility != "public" || is_write {
+        let uid = user_uid(&req, &state.db).await?;
+        authorize_repo_access(&req, &state.db, &repo, is_write).await?;
+
+        let handler = LfsHandler::new(
+            PathBuf::from(&repo.storage_path),
+            repo,
+            namespace,
+            state.db.clone(),
+        );
+        let response = handler
+            .batch_with_auth(batch_req, &base_url(&req), uid, &state.cache)
+            .await
+            .map_err(|_| {
+                actix_web::error::ErrorInternalServerError("LFS batch failed")
+            })?;
+        Ok(HttpResponse::Ok()
+            .content_type("application/vnd.git-lfs+json")
+            .json(response))
+    } else {
+        let handler = LfsHandler::new(
+            PathBuf::from(&repo.storage_path),
+            repo,
+            namespace,
+            state.db.clone(),
+        );
+        let response = handler
+            .batch(batch_req, &base_url(&req))
+            .await
+            .map_err(|_| {
+                actix_web::error::ErrorInternalServerError("LFS batch failed")
+            })?;
+        Ok(HttpResponse::Ok()
+            .content_type("application/vnd.git-lfs+json")
+            .json(response))
+    }
+}
+
+pub async fn lfs_upload(
+    req: HttpRequest,
+    path: web::Path<(String, String, String)>,
+    payload: web::Payload,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name, oid) = path.into_inner();
+
+    if !is_valid_lfs_oid(&oid) {
+        return Err(actix_web::error::ErrorBadRequest("Invalid OID format"));
+    }
+
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+    let token = bearer_token(&req)?;
+
+    let uid =
+        validate_lfs_token(&token, &state.cache, &state.db, repo.id, "upload")
+            .await?;
+    authorize_user_repo_access(&state.db, uid, &repo, true).await?;
+
+    let handler = LfsHandler::new(
+        PathBuf::from(&repo.storage_path),
+        repo.clone(),
+        namespace,
+        state.db.clone(),
+    );
+    let mut queue_lease =
+        acquire_lfs_write_queue(&state, &handler.model, "upload").await?;
+
+    let result = match handler.upload_object(&oid, payload).await {
+        Ok(response) => Ok(response),
+        Err(GitError::InvalidOid(_)) => {
+            Err(actix_web::error::ErrorBadRequest("Invalid OID"))
+        }
+        Err(GitError::AuthFailed(_)) => {
+            Err(actix_web::error::ErrorUnauthorized("Unauthorized"))
+        }
+        Err(_e) => {
+            Err(actix_web::error::ErrorInternalServerError("Upload failed"))
+        }
+    };
+    queue_lease.release().await;
+    result
+}
+
+pub async fn lfs_download(
+    req: HttpRequest,
+    path: web::Path<(String, String, String)>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name, oid) = path.into_inner();
+
+    if !is_valid_lfs_oid(&oid) {
+        return Err(actix_web::error::ErrorBadRequest("Invalid OID format"));
+    }
+
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+
+    if repo.visibility != "public" {
+        let token = bearer_token(&req)?;
+        let uid = validate_lfs_token(
+            &token,
+            &state.cache,
+            &state.db,
+            repo.id,
+            "download",
+        )
+        .await?;
+        authorize_user_repo_access(&state.db, uid, &repo, false).await?;
+    }
+
+    let handler = LfsHandler::new(
+        PathBuf::from(&repo.storage_path),
+        repo,
+        namespace,
+        state.db.clone(),
+    );
+
+    match handler.download_object(&oid).await {
+        Ok(response) => Ok(response),
+        Err(GitError::NotFound(_)) => {
+            Err(actix_web::error::ErrorNotFound("Object not found"))
+        }
+        Err(GitError::AuthFailed(_)) => {
+            Err(actix_web::error::ErrorUnauthorized("Unauthorized"))
+        }
+        Err(_e) => Err(actix_web::error::ErrorInternalServerError(
+            "Download failed",
+        )),
+    }
+}
+
+pub async fn lfs_lock_create(
+    req: HttpRequest,
+    path: web::Path<(String, String)>,
+    body: web::Json<CreateLockRequest>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name) = path.into_inner();
+
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+    let uid = user_uid(&req, &state.db).await?;
+    authorize_repo_access(&req, &state.db, &repo, true).await?;
+    let handler = LfsHandler::new(
+        PathBuf::from(&repo.storage_path),
+        repo.clone(),
+        namespace,
+        state.db.clone(),
+    );
+    let mut queue_lease =
+        acquire_lfs_write_queue(&state, &handler.model, "lock_create").await?;
+
+    let result = match handler.lock_object(&body.oid, uid).await {
+        Ok(lock) => Ok(HttpResponse::Created().json(lock)),
+        Err(GitError::Locked(msg)) => Ok(HttpResponse::Conflict().body(msg)),
+        Err(_e) => {
+            Err(actix_web::error::ErrorInternalServerError("Lock failed"))
+        }
+    };
+    queue_lease.release().await;
+    result
+}
+
+pub async fn lfs_lock_list(
+    req: HttpRequest,
+    path: web::Path<(String, String)>,
+    query: web::Query<std::collections::HashMap<String, String>>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name) = path.into_inner();
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+
+    if repo.visibility != "public" {
+        let uid = user_uid(&req, &state.db).await?;
+        authorize_user_repo_access(&state.db, uid, &repo, false).await?;
+    }
+
+    let maybe_oid = query.get("oid").map(|s| s.as_str());
+    let handler = LfsHandler::new(
+        PathBuf::from(&repo.storage_path),
+        repo,
+        namespace,
+        state.db.clone(),
+    );
+
+    match handler.list_locks(maybe_oid).await {
+        Ok(list) => Ok(HttpResponse::Ok().json(list)),
+        Err(_e) => Err(actix_web::error::ErrorInternalServerError(
+            "Lock list failed",
+        )),
+    }
+}
+
+pub async fn lfs_lock_get(
+    req: HttpRequest,
+    path: web::Path<(String, String, String)>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name, lock_id) = path.into_inner();
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+
+    if repo.visibility != "public" {
+        let uid = user_uid(&req, &state.db).await?;
+        authorize_user_repo_access(&state.db, uid, &repo, false).await?;
+    }
+
+    let handler = LfsHandler::new(
+        PathBuf::from(&repo.storage_path),
+        repo,
+        namespace,
+        state.db.clone(),
+    );
+
+    match handler.get_lock(&lock_id).await {
+        Ok(lock) => Ok(HttpResponse::Ok().json(lock)),
+        Err(GitError::NotFound(_)) => {
+            Err(actix_web::error::ErrorNotFound("Lock not found"))
+        }
+        Err(_e) => Err(actix_web::error::ErrorInternalServerError(
+            "Lock get failed",
+        )),
+    }
+}
+
+pub async fn lfs_lock_delete(
+    req: HttpRequest,
+    path: web::Path<(String, String, String)>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    let (namespace, repo_name, lock_id) = path.into_inner();
+
+    let repo = get_repo_model(&namespace, &repo_name, &state.db).await?;
+    let uid = user_uid(&req, &state.db).await?;
+    authorize_repo_access(&req, &state.db, &repo, true).await?;
+    let handler = LfsHandler::new(
+        PathBuf::from(&repo.storage_path),
+        repo.clone(),
+        namespace,
+        state.db.clone(),
+    );
+    let mut queue_lease =
+        acquire_lfs_write_queue(&state, &handler.model, "lock_delete").await?;
+
+    let result = match handler.unlock_object(&lock_id, uid).await {
+        Ok(()) => Ok(HttpResponse::NoContent().finish()),
+        Err(GitError::PermissionDenied(_)) => {
+            Err(actix_web::error::ErrorForbidden("Not allowed"))
+        }
+        Err(GitError::NotFound(_)) => {
+            Err(actix_web::error::ErrorNotFound("Lock not found"))
+        }
+        Err(_e) => Err(actix_web::error::ErrorInternalServerError(
+            "Lock delete failed",
+        )),
+    };
+    queue_lease.release().await;
+    result
+}
diff --git a/lib/git/http/mod.rs b/lib/git/http/mod.rs
new file mode 100644
index 0000000..3c524c0
--- /dev/null
+++ b/lib/git/http/mod.rs
@@ -0,0 +1,219 @@
+use std::{sync::Arc, time::Instant};
+
+use actix_web::{App, HttpResponse, HttpServer, dev::Service, web};
+use cache::AppCache;
+use config::AppConfig;
+use db::database::AppDatabase;
+use sqlx;
+
+pub mod action;
+pub mod auth;
+pub mod handler;
+pub mod lfs;
+pub mod lfs_routes;
+pub mod rate_limit;
+pub mod routes;
+pub mod utils;
+
+const REQUEST_LOG_EXCLUDED_PATHS: &[&str] = &[
+    "/health",
+    "/live",
+    "/ready",
+    "/metrics",
+    "/favicon.ico",
+    "/robots.txt",
+];
+
+fn should_log_request(path: &str) -> bool {
+    !REQUEST_LOG_EXCLUDED_PATHS.contains(&path)
+}
+
+#[derive(Clone)]
+pub struct HttpAppState {
+    pub db: AppDatabase,
+    pub cache: AppCache,
+    pub sync: crate::sync::ReceiveSyncService,
+    pub rate_limiter: Arc<rate_limit::RateLimiter>,
+    pub config: AppConfig,
+    pub git_state: crate::AppGitState,
+}
+
+async fn robots(state: web::Data<HttpAppState>) -> HttpResponse {
+    let sitemap_url = state
+        .config
+        .git_http_domain()
+        .map(|d| format!("{}/sitemap.xml", d.trim_end_matches('/')))
+        .unwrap_or_default();
+
+    let body = if sitemap_url.is_empty() {
+        "User-agent: *\nDisallow: /\n".to_string()
+    } else {
+        format!("User-agent: *\nDisallow: /\n\nSitemap: {sitemap_url}\n")
+    };
+
+    HttpResponse::Ok()
+        .content_type("text/plain; charset=utf-8")
+        .body(body)
+}
+
+async fn health(state: web::Data<HttpAppState>) -> HttpResponse {
+    let db_ok = sqlx::query("SELECT 1")
+        .execute(state.db.reader())
+        .await
+        .is_ok();
+    let cache_ok = state.cache.ping_cluster().await.is_ok();
+
+    if db_ok && cache_ok {
+        HttpResponse::Ok().json(serde_json::json!({
+            "status": "ok",
+            "db": "ok",
+            "cache": "ok",
+        }))
+    } else {
+        HttpResponse::ServiceUnavailable().json(serde_json::json!({
+            "status": "unhealthy",
+            "db": if db_ok { "ok" } else { "error" },
+            "cache": if cache_ok { "ok" } else { "error" },
+        }))
+    }
+}
+
+pub fn git_http_cfg(cfg: &mut web::ServiceConfig) {
+    cfg.route("/robots.txt", web::get().to(robots))
+        .route("/health", web::get().to(health))
+        .route(
+            "/{namespace}/{repo_name}.git/action",
+            web::get().to(action::action_poll),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/refs",
+            web::get().to(routes::info_refs),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/git-upload-pack",
+            web::post().to(routes::upload_pack),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/git-receive-pack",
+            web::post().to(routes::receive_pack),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/objects/batch",
+            web::post().to(lfs_routes::lfs_batch),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/objects/{oid}",
+            web::put().to(lfs_routes::lfs_upload),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/objects/{oid}",
+            web::get().to(lfs_routes::lfs_download),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/locks",
+            web::post().to(lfs_routes::lfs_lock_create),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/locks",
+            web::get().to(lfs_routes::lfs_lock_list),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/locks/{id}",
+            web::get().to(lfs_routes::lfs_lock_get),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/info/lfs/locks/{id}",
+            web::delete().to(lfs_routes::lfs_lock_delete),
+        )
+        .route(
+            "/{namespace}/{repo_name}.git/graphql",
+            web::post().to(crate::graphql::graphql_handle),
+        );
+}
+
+pub async fn run_http(
+    config: AppConfig,
+    db: AppDatabase,
+    cache: AppCache,
+    redis_pool: deadpool_redis::cluster::Pool,
+) -> anyhow::Result<()> {
+    let sync = crate::sync::ReceiveSyncService::new(redis_pool);
+
+    let rate_limiter = Arc::new(rate_limit::RateLimiter::new(
+        rate_limit::RateLimitConfig::default(),
+    ));
+    let _cleanup = rate_limiter.clone().start_cleanup();
+
+    let git_state = crate::AppGitState {
+        cache: cache.clone(),
+        db: db.clone(),
+    };
+
+    let state = HttpAppState {
+        db: db.clone(),
+        cache: cache.clone(),
+        sync,
+        rate_limiter,
+        config: config.clone(),
+        git_state,
+    };
+
+    let http_port = config.git_http_port()?;
+    tracing::info!("Starting git HTTP server on 0.0.0.0:{}", http_port);
+
+    let server = HttpServer::new(move || {
+        App::new()
+            .app_data(web::Data::new(state.clone()))
+            .wrap_fn(|req, srv| {
+                let should_log = should_log_request(req.path());
+                let method = req.method().clone();
+                let path = req.path().to_owned();
+                let peer_addr =
+                    req.connection_info().peer_addr().map(str::to_owned);
+                let started_at = Instant::now();
+                let fut = srv.call(req);
+
+                async move {
+                    match fut.await {
+                        Ok(res) => {
+                            if should_log {
+                                tracing::info!(
+                                    method = %method,
+                                    path = %path,
+                                    status = res.status().as_u16(),
+                                    elapsed_ms = started_at.elapsed().as_millis(),
+                                    peer_addr = peer_addr.as_deref().unwrap_or("-"),
+                                    "http request"
+                                );
+                            }
+                            Ok(res)
+                        }
+                        Err(err) => {
+                            if should_log {
+                                tracing::warn!(
+                                    method = %method,
+                                    path = %path,
+                                    elapsed_ms = started_at.elapsed().as_millis(),
+                                    peer_addr = peer_addr.as_deref().unwrap_or("-"),
+                                    error = %err,
+                                    "http request failed"
+                                );
+                            }
+                            Err(err)
+                        }
+                    }
+                }
+            })
+            .configure(git_http_cfg)
+    })
+    .bind(format!("0.0.0.0:{}", http_port))?
+    .run();
+
+    let result = server.await;
+    if let Err(e) = result {
+        tracing::error!("HTTP server error: {}", e);
+    }
+
+    tracing::info!("Git HTTP server stopped");
+    Ok(())
+}
diff --git a/lib/git/http/rate_limit.rs b/lib/git/http/rate_limit.rs
new file mode 100644
index 0000000..41d3107
--- /dev/null
+++ b/lib/git/http/rate_limit.rs
@@ -0,0 +1,128 @@
+use std::{
+    collections::HashMap,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+use tokio::{sync::RwLock, time::interval};
+
+#[derive(Debug, Clone)]
+pub struct RateLimitConfig {
+    pub read_requests_per_window: u32,
+    pub write_requests_per_window: u32,
+    pub window_secs: u64,
+}
+
+impl Default for RateLimitConfig {
+    fn default() -> Self {
+        Self {
+            read_requests_per_window: 120,
+            write_requests_per_window: 30,
+            window_secs: 60,
+        }
+    }
+}
+
+#[derive(Debug)]
+struct RateLimitBucket {
+    read_count: u32,
+    write_count: u32,
+    reset_time: Instant,
+}
+
+#[derive(Clone, Copy)]
+enum BucketOp {
+    Read,
+    Write,
+}
+
+pub struct RateLimiter {
+    buckets: Arc<RwLock<HashMap<String, RateLimitBucket>>>,
+    config: RateLimitConfig,
+}
+
+impl RateLimiter {
+    pub fn new(config: RateLimitConfig) -> Self {
+        Self {
+            buckets: Arc::new(RwLock::new(HashMap::new())),
+            config,
+        }
+    }
+
+    pub async fn is_read_allowed(&self) -> bool {
+        self.is_allowed(
+            "global:read",
+            BucketOp::Read,
+            self.config.read_requests_per_window,
+        )
+        .await
+    }
+
+    pub async fn is_write_allowed(&self) -> bool {
+        self.is_allowed(
+            "global:write",
+            BucketOp::Write,
+            self.config.write_requests_per_window,
+        )
+        .await
+    }
+
+    pub async fn is_repo_write_allowed(&self, repo_path: &str) -> bool {
+        let key = format!("repo:write:{}", repo_path);
+        self.is_allowed(
+            &key,
+            BucketOp::Write,
+            self.config.write_requests_per_window,
+        )
+        .await
+    }
+
+    async fn is_allowed(&self, key: &str, op: BucketOp, limit: u32) -> bool {
+        let now = Instant::now();
+        let mut buckets = self.buckets.write().await;
+
+        let bucket =
+            buckets
+                .entry(key.to_string())
+                .or_insert_with(|| RateLimitBucket {
+                    read_count: 0,
+                    write_count: 0,
+                    reset_time: now
+                        + Duration::from_secs(self.config.window_secs),
+                });
+
+        if now >= bucket.reset_time {
+            bucket.read_count = 0;
+            bucket.write_count = 0;
+            bucket.reset_time =
+                now + Duration::from_secs(self.config.window_secs);
+        }
+
+        let over_limit = match op {
+            BucketOp::Read => bucket.read_count >= limit,
+            BucketOp::Write => bucket.write_count >= limit,
+        };
+
+        if over_limit {
+            return false;
+        }
+
+        match op {
+            BucketOp::Read => bucket.read_count += 1,
+            BucketOp::Write => bucket.write_count += 1,
+        }
+        true
+    }
+
+    pub fn start_cleanup(self: Arc<Self>) -> tokio::task::JoinHandle<()> {
+        tokio::spawn(async move {
+            let mut ticker = interval(Duration::from_secs(300));
+            loop {
+                ticker.tick().await;
+                let now = Instant::now();
+                let mut buckets = self.buckets.write().await;
+                buckets.retain(|_, bucket| now < bucket.reset_time);
+            }
+        })
+    }
+}
diff --git a/lib/git/http/routes.rs b/lib/git/http/routes.rs
new file mode 100644
index 0000000..6498201
--- /dev/null
+++ b/lib/git/http/routes.rs
@@ -0,0 +1,179 @@
+use std::{path::PathBuf, time::Duration};
+
+use actix_web::{Error, HttpRequest, HttpResponse, web};
+use tokio::time::timeout;
+
+use crate::{
+    http::{
+        HttpAppState, auth::authorize_repo_access, handler::GitHttpHandler,
+        utils::get_repo_model,
+    },
+    sync::{
+        RepoReceiveSyncTask,
+        push_queue::{
+            PushQueueEvent, PushQueueWaitError, wait_for_push_queue_slot,
+        },
+    },
+};
+
+pub async fn info_refs(
+    req: HttpRequest,
+    path: web::Path<(String, String)>,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    if !state.rate_limiter.is_read_allowed().await {
+        return Err(actix_web::error::ErrorTooManyRequests(
+            "Rate limit exceeded",
+        ));
+    }
+
+    let service_param = req
+        .query_string()
+        .split('&')
+        .find(|s| s.starts_with("service="))
+        .and_then(|s| s.strip_prefix("service="))
+        .ok_or_else(|| {
+            actix_web::error::ErrorBadRequest("Missing service parameter")
+        })?;
+
+    if service_param != "git-upload-pack" && service_param != "git-receive-pack"
+    {
+        return Err(actix_web::error::ErrorBadRequest("Invalid service"));
+    }
+
+    let path_inner = path.into_inner();
+    let model = get_repo_model(&path_inner.0, &path_inner.1, &state.db).await?;
+    let is_write = service_param == "git-receive-pack";
+    authorize_repo_access(&req, &state.db, &model, is_write).await?;
+
+    let storage_path = PathBuf::from(&model.storage_path);
+    let handler = GitHttpHandler::new(storage_path, model, state.db.clone());
+    handler.info_refs(service_param).await
+}
+
+pub async fn upload_pack(
+    req: HttpRequest,
+    path: web::Path<(String, String)>,
+    payload: web::Payload,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    if !state.rate_limiter.is_read_allowed().await {
+        return Err(actix_web::error::ErrorTooManyRequests(
+            "Rate limit exceeded",
+        ));
+    }
+
+    let path_inner = path.into_inner();
+    let model = get_repo_model(&path_inner.0, &path_inner.1, &state.db).await?;
+    authorize_repo_access(&req, &state.db, &model, false).await?;
+
+    let storage_path = PathBuf::from(&model.storage_path);
+    let handler = GitHttpHandler::new(storage_path, model, state.db.clone());
+    handler.upload_pack(payload).await
+}
+
+pub async fn receive_pack(
+    req: HttpRequest,
+    path: web::Path<(String, String)>,
+    payload: web::Payload,
+    state: web::Data<HttpAppState>,
+) -> Result<HttpResponse, Error> {
+    if !state.rate_limiter.is_write_allowed().await {
+        return Err(actix_web::error::ErrorTooManyRequests(
+            "Rate limit exceeded",
+        ));
+    }
+
+    let path_inner = path.into_inner();
+    let model = get_repo_model(&path_inner.0, &path_inner.1, &state.db).await?;
+    authorize_repo_access(&req, &state.db, &model, true).await?;
+
+    let mut push_queue_lease = match wait_for_push_queue_slot(
+        state.sync.clone(),
+        model.id,
+        |event, request_id| {
+            let request_id = request_id.to_string();
+            let repo_name = model.name.clone();
+            let repo_id = model.id;
+            match event {
+                PushQueueEvent::Waiting(position) => {
+                    tracing::info!(
+                        repo = %repo_name,
+                        repo_id = %repo_id,
+                        request_id = %request_id,
+                        position = position.position,
+                        total = position.total,
+                        "http_push_queue_waiting"
+                    );
+                }
+                PushQueueEvent::Acquired => {
+                    tracing::info!(
+                        repo = %repo_name,
+                        repo_id = %repo_id,
+                        request_id = %request_id,
+                        "http_push_queue_acquired"
+                    );
+                }
+            }
+        },
+    )
+    .await
+    {
+        Ok(lease) => lease,
+        Err(PushQueueWaitError::Join(e)) => {
+            tracing::error!(
+                error = %e,
+                repo = %model.name,
+                repo_id = %model.id,
+                "http_push_queue_join_failed"
+            );
+            return Err(actix_web::error::ErrorServiceUnavailable(
+                "Push queue is temporarily unavailable. Please retry later.",
+            ));
+        }
+        Err(PushQueueWaitError::Lock(e)) => {
+            tracing::error!(
+                error = %e,
+                repo = %model.name,
+                repo_id = %model.id,
+                "http_push_queue_lock_failed"
+            );
+            return Err(actix_web::error::ErrorServiceUnavailable(
+                "Push queue lock failed. Please retry later.",
+            ));
+        }
+        Err(PushQueueWaitError::Timeout) => {
+            tracing::info!(
+                repo = %model.name,
+                repo_id = %model.id,
+                "http_push_queue_timeout"
+            );
+            return Ok(HttpResponse::ServiceUnavailable()
+                .insert_header(("Retry-After", "5"))
+                .content_type("text/plain; charset=utf-8")
+                .body("Push queue timed out. Please retry in a moment.\n"));
+        }
+    };
+
+    let storage_path = PathBuf::from(&model.storage_path);
+    let handler =
+        GitHttpHandler::new(storage_path, model.clone(), state.db.clone());
+    let result = handler.receive_pack(payload).await;
+    push_queue_lease.release().await;
+
+    if result.is_ok() {
+        let _ = tokio::spawn({
+            let sync = state.sync.clone();
+            let repo_uid = model.id;
+            async move {
+                let _ = timeout(
+                    Duration::from_secs(5),
+                    sync.send(RepoReceiveSyncTask { repo_uid }),
+                )
+                .await;
+            }
+        });
+    }
+
+    result
+}
diff --git a/lib/git/http/utils.rs b/lib/git/http/utils.rs
new file mode 100644
index 0000000..1990124
--- /dev/null
+++ b/lib/git/http/utils.rs
@@ -0,0 +1,98 @@
+use actix_web::{Error, HttpRequest};
+use base64::{Engine, engine::general_purpose::STANDARD};
+use db::database::AppDatabase;
+use model::{
+    repos::RepoModel,
+    workspace::{
+        wk_history_name::WkHistoryNameModel, workspace::WorkspaceModel,
+    },
+};
+
+pub async fn get_repo_model(
+    namespace: &str,
+    repo_name: &str,
+    db: &AppDatabase,
+) -> Result<RepoModel, Error> {
+    let wk_id = if let Some(wk) = sqlx::query_as::<_, WorkspaceModel>(
+        "SELECT id, name, description, avatar_url, created_at FROM workspace WHERE name = $1",
+    )
+    .bind(namespace)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorInternalServerError("Database error"))?
+    {
+        wk.id
+    } else if let Some(history) = sqlx::query_as::<_, WkHistoryNameModel>(
+        "SELECT id, wk, name, changed_by, created_at FROM wk_history_name WHERE name = $1",
+    )
+    .bind(namespace)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorInternalServerError("Database error"))?
+    {
+        history.wk
+    } else {
+        return Err(actix_web::error::ErrorNotFound("Project not found").into());
+    };
+
+    let repo = sqlx::query_as::<_, RepoModel>(
+        "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+                is_archived, is_template, is_mirror, created_by, storage_path, \
+                created_at, updated_at, deleted_at \
+         FROM repo \
+         WHERE name = $1 AND wk = $2 AND deleted_at IS NULL",
+    )
+    .bind(repo_name)
+    .bind(wk_id)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|_| actix_web::error::ErrorInternalServerError("Database error"))?
+    .ok_or_else(|| actix_web::error::ErrorNotFound("Repository not found"))?;
+
+    Ok(repo)
+}
+
+pub fn extract_basic_credentials(
+    req: &HttpRequest,
+) -> Result<(String, String), Error> {
+    let auth_header = req
+        .headers()
+        .get("authorization")
+        .ok_or_else(|| {
+            actix_web::error::ErrorUnauthorized("Missing authorization header")
+        })?
+        .to_str()
+        .map_err(|_| {
+            actix_web::error::ErrorUnauthorized("Invalid authorization header")
+        })?;
+
+    let encoded = auth_header.strip_prefix("Basic ").ok_or_else(|| {
+        actix_web::error::ErrorUnauthorized("Invalid authorization scheme")
+    })?;
+
+    let decoded = STANDARD.decode(encoded).map_err(|_| {
+        actix_web::error::ErrorUnauthorized(
+            "Invalid basic authorization encoding",
+        )
+    })?;
+
+    let decoded = String::from_utf8(decoded).map_err(|_| {
+        actix_web::error::ErrorUnauthorized(
+            "Invalid basic authorization payload",
+        )
+    })?;
+
+    let (username, access_key) = decoded.split_once(':').ok_or_else(|| {
+        actix_web::error::ErrorUnauthorized(
+            "Invalid basic authorization format",
+        )
+    })?;
+
+    if username.is_empty() || access_key.is_empty() {
+        return Err(actix_web::error::ErrorUnauthorized(
+            "Username or access key is empty",
+        ));
+    }
+
+    Ok((username.to_string(), access_key.to_string()))
+}
diff --git a/lib/git/lib.rs b/lib/git/lib.rs
new file mode 100644
index 0000000..ef04d76
--- /dev/null
+++ b/lib/git/lib.rs
@@ -0,0 +1,18 @@
+use cache::AppCache;
+use db::database::AppDatabase;
+
+pub mod bare;
+pub mod cmd;
+pub mod errors;
+pub mod graphql;
+pub mod http;
+pub mod rpc;
+pub mod ssh;
+pub mod sync;
+#[derive(Clone)]
+pub struct AppGitState {
+    pub cache: AppCache,
+    pub db: AppDatabase,
+}
+
+pub mod role;
diff --git a/lib/git/proto/archive.proto b/lib/git/proto/archive.proto
new file mode 100644
index 0000000..15d2593
--- /dev/null
+++ b/lib/git/proto/archive.proto
@@ -0,0 +1,40 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/archive/mod.rs — ArchiveOptions
+message ArchiveOptions {
+  ObjectId tree = 1;
+  optional string prefix = 2;
+  repeated string pathspec = 3;
+}
+
+// Mirrors: cmd/archive/mod.rs — ArchiveResult
+message ArchiveResult {
+  bytes bytes = 1;
+}
+
+message ArchiveTarRequest {
+  string repo_id = 1;
+  ArchiveOptions options = 2;
+}
+
+message ArchiveTarResponse {
+  bytes data = 1;
+}
+
+message ArchiveZipRequest {
+  string repo_id = 1;
+  ArchiveOptions options = 2;
+}
+
+message ArchiveZipResponse {
+  bytes data = 1;
+}
+
+service ArchiveService {
+  rpc ArchiveTar(ArchiveTarRequest) returns (ArchiveTarResponse);
+  rpc ArchiveZip(ArchiveZipRequest) returns (ArchiveZipResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/blame.proto b/lib/git/proto/blame.proto
new file mode 100644
index 0000000..a3c9a6c
--- /dev/null
+++ b/lib/git/proto/blame.proto
@@ -0,0 +1,75 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/blame/mod.rs — CommitBlameHunk
+message CommitBlameHunk {
+  ObjectId commit_oid = 1;
+  uint32 final_start_line = 2;
+  uint32 final_lines = 3;
+  uint32 orig_start_line = 4;
+  uint32 orig_lines = 5;
+  bool boundary = 6;
+  optional string orig_path = 7;
+}
+
+// Mirrors: cmd/blame/mod.rs — CommitBlameLine
+message CommitBlameLine {
+  ObjectId commit_oid = 1;
+  uint32 line_no = 2;
+  string content = 3;
+  optional string orig_path = 4;
+}
+
+// Mirrors: cmd/blame/mod.rs — BlameOptions
+message BlameOptions {
+  optional uint64 min_line = 1;
+  optional uint64 max_line = 2;
+  bool track_copies_same_file = 3;
+  bool track_copies_same_commit_moves = 4;
+  bool ignore_whitespace = 5;
+}
+
+message BlameFileRequest {
+  string repo_id = 1;
+  string path = 2;
+  optional string rev = 3;
+  optional BlameOptions options = 4;
+}
+
+message BlameFileResponse {
+  repeated CommitBlameHunk hunks = 1;
+}
+
+message BlameHunkRequest {
+  string repo_id = 1;
+  string path = 2;
+  optional string rev = 3;
+  uint32 start_line = 4;
+  uint32 end_line = 5;
+}
+
+message BlameHunkResponse {
+  repeated CommitBlameHunk hunks = 1;
+}
+
+message BlameLinesRequest {
+  string repo_id = 1;
+  string path = 2;
+  optional string rev = 3;
+  uint32 start_line = 4;
+  uint32 end_line = 5;
+}
+
+message BlameLinesResponse {
+  repeated CommitBlameLine lines = 1;
+}
+
+service BlameService {
+  rpc BlameFile(BlameFileRequest) returns (BlameFileResponse);
+  rpc BlameStream(BlameFileRequest) returns (stream CommitBlameHunk);
+  rpc BlameHunk(BlameHunkRequest) returns (BlameHunkResponse);
+  rpc BlameLines(BlameLinesRequest) returns (BlameLinesResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/blob.proto b/lib/git/proto/blob.proto
new file mode 100644
index 0000000..8e65709
--- /dev/null
+++ b/lib/git/proto/blob.proto
@@ -0,0 +1,113 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/blob/blob_load.rs — BlobLoadParams
+message BlobLoadParams {
+  ObjectId id = 1;
+  string path = 2;
+}
+
+// Mirrors: cmd/blob/blob_load.rs — BlobLoadResult
+message BlobLoadResult {
+  BlobLoadParams params = 1;
+  bytes blob = 2;
+}
+
+// Mirrors: cmd/blob/blob_size.rs — BlobSizeParams
+message BlobSizeParams {
+  ObjectId id = 1;
+  string path = 2;
+}
+
+// Mirrors: cmd/blob/blob_upload.rs — BlobUploadParams
+message BlobUploadParams {
+  bytes blob = 1;
+  string path = 2;
+}
+
+// Mirrors: cmd/blob/blob_upload.rs — BlobUploadResult
+message BlobUploadResult {
+  ObjectId id = 1;
+}
+
+// Mirrors: cmd/blob/blob_chunk.rs — BlobChunkParam
+message BlobChunkParam {
+  string path = 1;
+  ObjectId oid = 2;
+  uint64 size = 3;
+  uint64 offset = 4;
+}
+
+// Mirrors: cmd/blob/blob_chunk.rs — BlobChunk
+message BlobChunk {
+  BlobChunkParam param = 1;
+  bytes chunk = 2;
+}
+
+message BlobLoadRequest {
+  string repo_id = 1;
+  ObjectId id = 2;
+  string path = 3;
+}
+
+message BlobLoadResponse {
+  bytes blob = 1;
+}
+
+message BlobSizeRequest {
+  string repo_id = 1;
+  ObjectId id = 2;
+  string path = 3;
+}
+
+message BlobSizeResponse {
+  uint64 size = 1;
+}
+
+message BlobExistsRequest {
+  string repo_id = 1;
+  ObjectId id = 2;
+}
+
+message BlobExistsResponse {
+  bool exists = 1;
+}
+
+message BlobIsBinaryRequest {
+  string repo_id = 1;
+  ObjectId id = 2;
+}
+
+message BlobIsBinaryResponse {
+  bool is_binary = 1;
+}
+
+message BlobUploadRequest {
+  string repo_id = 1;
+  bytes blob = 2;
+  string path = 3;
+}
+
+message BlobUploadResponse {
+  ObjectId id = 1;
+}
+
+message BlobChunkRequest {
+  string repo_id = 1;
+  string path = 2;
+  ObjectId oid = 3;
+  uint64 size = 4;
+  uint64 offset = 5;
+}
+
+service BlobService {
+  rpc BlobLoad(BlobLoadRequest) returns (BlobLoadResponse);
+  rpc BlobSize(BlobSizeRequest) returns (BlobSizeResponse);
+  rpc BlobExists(BlobExistsRequest) returns (BlobExistsResponse);
+  rpc BlobIsBinary(BlobIsBinaryRequest) returns (BlobIsBinaryResponse);
+  rpc BlobUpload(BlobUploadRequest) returns (BlobUploadResponse);
+  rpc BlobChunkStream(BlobChunkRequest) returns (stream BlobChunk);
+}
\ No newline at end of file
diff --git a/lib/git/proto/branch.proto b/lib/git/proto/branch.proto
new file mode 100644
index 0000000..9516d86
--- /dev/null
+++ b/lib/git/proto/branch.proto
@@ -0,0 +1,128 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/branch/branch_list.rs — BranchListItem
+message BranchListItem {
+  string name = 1;
+  ObjectId oid = 2;
+  bool is_head = 3;
+  bool is_remote = 4;
+  bool is_current = 5;
+  optional string upstream = 6;
+}
+
+// Mirrors: cmd/branch/branch_summary.rs — BranchSummary
+message BranchSummary {
+  uint64 local_count = 1;
+  uint64 remote_count = 2;
+  uint64 all_count = 3;
+}
+
+// Mirrors: cmd/branch/branch_fork.rs — BranchForkParams
+message BranchForkParams {
+  string name = 1;
+  ObjectId oid = 2;
+  bool force = 3;
+}
+
+// Mirrors: cmd/branch/branch_delete.rs — BranchDeleteParams
+message BranchDeleteParams {
+  string name = 1;
+  bool force = 2;
+}
+
+// Mirrors: cmd/branch/branch_rename.rs — BranchReNameParams
+message BranchReNameParams {
+  string old_branch = 1;
+  string new_branch = 2;
+  bool force = 3;
+}
+
+message BranchListRequest {
+  string repo_id = 1;
+}
+
+message BranchListResponse {
+  repeated BranchListItem branches = 1;
+}
+
+message BranchInfoRequest {
+  string repo_id = 1;
+  string branch = 2;
+}
+
+message BranchInfoResponse {
+  BranchListItem branch = 1;
+}
+
+message BranchSummaryRequest {
+  string repo_id = 1;
+}
+
+message BranchSummaryResponse {
+  BranchSummary summary = 1;
+}
+
+message BranchHeadRequest {
+  string repo_id = 1;
+}
+
+message BranchHeadResponse {
+  string head_name = 1;
+}
+
+message BranchAheadBehindRequest {
+  string repo_id = 1;
+  string local_branch = 2;
+  string remote_branch = 3;
+}
+
+message BranchAheadBehindResponse {
+  uint64 ahead = 1;
+  uint64 behind = 2;
+}
+
+message BranchUpstreamRequest {
+  string repo_id = 1;
+  string branch = 2;
+}
+
+message BranchUpstreamResponse {
+  string upstream_name = 1;
+}
+
+message BranchForkRequest {
+  string repo_id = 1;
+  BranchForkParams params = 2;
+}
+
+message BranchForkResponse {}
+
+message BranchDeleteRequest {
+  string repo_id = 1;
+  BranchDeleteParams params = 2;
+}
+
+message BranchDeleteResponse {}
+
+message BranchRenameRequest {
+  string repo_id = 1;
+  BranchReNameParams params = 2;
+}
+
+message BranchRenameResponse {}
+
+service BranchService {
+  rpc BranchList(BranchListRequest) returns (BranchListResponse);
+  rpc BranchInfo(BranchInfoRequest) returns (BranchInfoResponse);
+  rpc BranchSummary(BranchSummaryRequest) returns (BranchSummaryResponse);
+  rpc BranchHead(BranchHeadRequest) returns (BranchHeadResponse);
+  rpc BranchAheadBehind(BranchAheadBehindRequest) returns (BranchAheadBehindResponse);
+  rpc BranchUpstream(BranchUpstreamRequest) returns (BranchUpstreamResponse);
+  rpc BranchFork(BranchForkRequest) returns (BranchForkResponse);
+  rpc BranchDelete(BranchDeleteRequest) returns (BranchDeleteResponse);
+  rpc BranchRename(BranchRenameRequest) returns (BranchRenameResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/commit.proto b/lib/git/proto/commit.proto
new file mode 100644
index 0000000..b3ef1bd
--- /dev/null
+++ b/lib/git/proto/commit.proto
@@ -0,0 +1,183 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/commit/mod.rs — CommitMeta
+message CommitMeta {
+  ObjectId oid = 1;
+  string message = 2;
+  string summary = 3;
+  CommitSignature author = 4;
+  CommitSignature committer = 5;
+  ObjectId tree_id = 6;
+  repeated ObjectId parent_ids = 7;
+  optional string encoding = 8;
+}
+
+// Mirrors: cmd/commit/mod.rs — CommitRefInfo
+message CommitRefInfo {
+  string name = 1;
+  ObjectId target = 2;
+  bool is_remote = 3;
+  bool is_tag = 4;
+}
+
+// Mirrors: cmd/commit/commit_summary.rs — CommitSummary
+message CommitSummary {
+  optional CommitMeta head = 1;
+  uint64 count = 2;
+}
+
+// Mirrors: cmd/commit/commit_walker.rs — CommitWalkSort
+enum CommitWalkSort {
+  COMMIT_WALK_SORT_NONE = 0;
+  COMMIT_WALK_SORT_TOPOLOGICAL = 1;
+  COMMIT_WALK_SORT_TIME = 2;
+  COMMIT_WALK_SORT_REVERSE = 3;
+}
+
+// Mirrors: cmd/commit/commit_walker.rs — CommitWalkParams
+message CommitWalkParams {
+  repeated ObjectId start_oids = 1;
+  repeated ObjectId hide_oids = 2;
+  optional uint64 limit = 3;
+  uint64 skip = 4;
+  bool first_parent = 5;
+  CommitWalkSort sort = 6;
+}
+
+// Mirrors: cmd/commit/commit_cherry_pick.rs — CommitCherryPickParams
+message CommitCherryPickParams {
+  ObjectId cherrypick_oid = 1;
+  CommitSignature author = 2;
+  CommitSignature committer = 3;
+  optional string message = 4;
+  uint32 mainline = 5;
+  optional string update_ref = 6;
+}
+
+// Mirrors: cmd/commit/commit_cherry_pick.rs — CommitCherryPickSequence
+message CommitCherryPickSequence {
+  repeated ObjectId cherrypick_oids = 1;
+  CommitSignature author = 2;
+  CommitSignature committer = 3;
+  optional string update_ref = 4;
+}
+
+message CommitInfoRequest {
+  string repo_id = 1;
+  ObjectId oid = 2;
+}
+
+message CommitInfoResponse {
+  CommitMeta commit = 1;
+}
+
+message CommitHistoryRequest {
+  string repo_id = 1;
+  uint64 limit = 2;
+  uint64 skip = 3;
+  CommitWalkSort sort = 4;
+  optional string branch = 5;
+}
+
+message CommitHistoryResponse {
+  repeated CommitMeta commits = 1;
+}
+
+message CommitSummaryRequest {
+  string repo_id = 1;
+}
+
+message CommitSummaryResponse {
+  CommitSummary summary = 1;
+}
+
+message CommitWalkRequest {
+  string repo_id = 1;
+  CommitWalkParams params = 2;
+}
+
+message CommitWalkResponse {
+  repeated CommitMeta commits = 1;
+}
+
+message CommitRefsRequest {
+  string repo_id = 1;
+}
+
+message CommitRefsResponse {
+  repeated CommitRefInfo refs = 1;
+}
+
+message CommitPrefixRequest {
+  string repo_id = 1;
+  string prefix = 2;
+}
+
+message CommitPrefixResponse {
+  ObjectId oid = 1;
+}
+
+message CommitExistsRequest {
+  string repo_id = 1;
+  ObjectId oid = 2;
+}
+
+message CommitExistsResponse {
+  bool exists = 1;
+}
+
+message CherryPickRequest {
+  string repo_id = 1;
+  CommitCherryPickParams params = 2;
+}
+
+message CherryPickResponse {
+  ObjectId oid = 1;
+}
+
+message CherryPickSequenceRequest {
+  string repo_id = 1;
+  CommitCherryPickSequence params = 2;
+}
+
+message CherryPickSequenceResponse {
+  ObjectId oid = 1;
+}
+
+message FileChange {
+  string path = 1;
+  bytes content = 2;
+}
+
+message CreateCommitRequest {
+  string repo_id = 1;
+  string branch = 2;
+  string message = 3;
+  string author_name = 4;
+  string author_email = 5;
+  string committer_name = 6;
+  string committer_email = 7;
+  repeated FileChange files = 8;
+}
+
+message CreateCommitResponse {
+  ObjectId oid = 1;
+}
+
+service CommitService {
+  rpc CommitInfo(CommitInfoRequest) returns (CommitInfoResponse);
+  rpc CommitHistory(CommitHistoryRequest) returns (CommitHistoryResponse);
+  rpc CommitHistoryStream(CommitHistoryRequest) returns (stream CommitMeta);
+  rpc CommitSummary(CommitSummaryRequest) returns (CommitSummaryResponse);
+  rpc CommitWalk(CommitWalkRequest) returns (CommitWalkResponse);
+  rpc CommitRefs(CommitRefsRequest) returns (CommitRefsResponse);
+  rpc CommitPrefix(CommitPrefixRequest) returns (CommitPrefixResponse);
+  rpc CommitExists(CommitExistsRequest) returns (CommitExistsResponse);
+  rpc CherryPick(CherryPickRequest) returns (CherryPickResponse);
+  rpc CherryPickSequence(CherryPickSequenceRequest) returns (CherryPickSequenceResponse);
+  rpc CreateCommit(CreateCommitRequest) returns (CreateCommitResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/common.proto b/lib/git/proto/common.proto
new file mode 100644
index 0000000..48f636f
--- /dev/null
+++ b/lib/git/proto/common.proto
@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package git.v1;
+
+// Mirrors: cmd/oid.rs — ObjectId(pub String)
+message ObjectId {
+  string value = 1;
+}
+
+// Mirrors: cmd/commit/mod.rs — CommitSignature
+message CommitSignature {
+  string name = 1;
+  string email = 2;
+  int64 time_secs = 3;
+  int32 offset_minutes = 4;
+}
+
+// Mirrors: cmd/tagger.rs — GitTagger
+message GitTagger {
+  string name = 1;
+  string email = 2;
+}
\ No newline at end of file
diff --git a/lib/git/proto/diff.proto b/lib/git/proto/diff.proto
new file mode 100644
index 0000000..eff8c23
--- /dev/null
+++ b/lib/git/proto/diff.proto
@@ -0,0 +1,174 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/diff/mod.rs — DiffDeltaStatus
+enum DiffDeltaStatus {
+  DIFF_DELTA_STATUS_UNMODIFIED = 0;
+  DIFF_DELTA_STATUS_ADDED = 1;
+  DIFF_DELTA_STATUS_DELETED = 2;
+  DIFF_DELTA_STATUS_MODIFIED = 3;
+  DIFF_DELTA_STATUS_RENAMED = 4;
+  DIFF_DELTA_STATUS_COPIED = 5;
+  DIFF_DELTA_STATUS_TYPECHANGE = 6;
+  DIFF_DELTA_STATUS_CONFLICTED = 7;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffFile
+message DiffFile {
+  ObjectId oid = 1;
+  optional string path = 2;
+  uint64 size = 3;
+  bool is_binary = 4;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffHunk
+message DiffHunk {
+  uint32 old_start = 1;
+  uint32 old_lines = 2;
+  uint32 new_start = 3;
+  uint32 new_lines = 4;
+  string header = 5;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffDelta
+message DiffDelta {
+  DiffDeltaStatus status = 1;
+  DiffFile old_file = 2;
+  DiffFile new_file = 3;
+  uint32 nfiles = 4;
+  repeated DiffHunk hunks = 5;
+  repeated DiffLine lines = 6;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffLine
+message DiffLine {
+  string content = 1;
+  string origin = 2;
+  optional uint32 old_lineno = 3;
+  optional uint32 new_lineno = 4;
+  uint32 num_lines = 5;
+  int64 content_offset = 6;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffStats
+message DiffStats {
+  uint64 files_changed = 1;
+  uint64 insertions = 2;
+  uint64 deletions = 3;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffResult
+message DiffResult {
+  DiffStats stats = 1;
+  repeated DiffDelta deltas = 2;
+}
+
+// Mirrors: cmd/diff/mod.rs — DiffOptions
+message DiffOptions {
+  uint32 context_lines = 1;
+  repeated string pathspec = 2;
+  bool ignore_whitespace = 3;
+  bool force_text = 4;
+  bool reverse = 5;
+}
+
+// Mirrors: cmd/diff/mod.rs — SideBySideChangeType
+enum SideBySideChangeType {
+  SIDE_BY_SIDE_CHANGE_TYPE_UNCHANGED = 0;
+  SIDE_BY_SIDE_CHANGE_TYPE_ADDED = 1;
+  SIDE_BY_SIDE_CHANGE_TYPE_REMOVED = 2;
+  SIDE_BY_SIDE_CHANGE_TYPE_MODIFIED = 3;
+  SIDE_BY_SIDE_CHANGE_TYPE_EMPTY = 4;
+}
+
+// Mirrors: cmd/diff/mod.rs — SideBySideLine
+message SideBySideLine {
+  optional uint32 left_line_no = 1;
+  optional uint32 right_line_no = 2;
+  string left_content = 3;
+  string right_content = 4;
+  SideBySideChangeType change_type = 5;
+}
+
+// Mirrors: cmd/diff/mod.rs — SideBySideFile
+message SideBySideFile {
+  string path = 1;
+  uint64 additions = 2;
+  uint64 deletions = 3;
+  bool is_binary = 4;
+  bool is_rename = 5;
+  repeated SideBySideLine lines = 6;
+}
+
+// Mirrors: cmd/diff/mod.rs — SideBySideDiffResult
+message SideBySideDiffResult {
+  repeated SideBySideFile files = 1;
+  uint64 total_additions = 2;
+  uint64 total_deletions = 3;
+}
+
+message DiffStatsRequest {
+  string repo_id = 1;
+  ObjectId old_oid = 2;
+  ObjectId new_oid = 3;
+  optional DiffOptions options = 4;
+}
+
+message DiffStatsResponse {
+  DiffResult result = 1;
+}
+
+message DiffPatchRequest {
+  string repo_id = 1;
+  ObjectId old_oid = 2;
+  ObjectId new_oid = 3;
+  optional DiffOptions options = 4;
+}
+
+message DiffPatchResponse {
+  DiffResult result = 1;
+}
+
+message DiffPatchSideBySideRequest {
+  string repo_id = 1;
+  ObjectId old_oid = 2;
+  ObjectId new_oid = 3;
+  optional DiffOptions options = 4;
+}
+
+message DiffPatchSideBySideResponse {
+  SideBySideDiffResult result = 1;
+}
+
+message DiffTreeToTreeRequest {
+  string repo_id = 1;
+  ObjectId old_tree = 2;
+  ObjectId new_tree = 3;
+  optional DiffOptions options = 4;
+}
+
+message DiffTreeToTreeResponse {
+  DiffResult result = 1;
+}
+
+message DiffIndexToTreeRequest {
+  string repo_id = 1;
+  ObjectId tree_oid = 2;
+  optional DiffOptions options = 3;
+}
+
+message DiffIndexToTreeResponse {
+  DiffResult result = 1;
+}
+
+service DiffService {
+  rpc DiffStats(DiffStatsRequest) returns (DiffStatsResponse);
+  rpc DiffPatch(DiffPatchRequest) returns (DiffPatchResponse);
+  rpc DiffStream(DiffPatchRequest) returns (stream DiffDelta);
+  rpc DiffPatchSideBySide(DiffPatchSideBySideRequest) returns (DiffPatchSideBySideResponse);
+  rpc DiffTreeToTree(DiffTreeToTreeRequest) returns (DiffTreeToTreeResponse);
+  rpc DiffIndexToTree(DiffIndexToTreeRequest) returns (DiffIndexToTreeResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/fork.proto b/lib/git/proto/fork.proto
new file mode 100644
index 0000000..cfc0561
--- /dev/null
+++ b/lib/git/proto/fork.proto
@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Fork a bare repository from an existing source repo.
+message ForkRepoParams {
+  string namespace = 1;
+  string repo_name = 2;
+  string default_branch = 3;
+  optional string description = 4;
+  bool enable_lfs = 5;
+}
+
+message ForkBareRequest {
+  string storage_root = 1;
+  string source_storage_path = 2;
+  ForkRepoParams params = 3;
+}
+
+message ForkBareResponse {
+  string storage_path = 1;
+}
+
+service ForkService {
+  rpc ForkBare(ForkBareRequest) returns (ForkBareResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/init.proto b/lib/git/proto/init.proto
new file mode 100644
index 0000000..56a8b70
--- /dev/null
+++ b/lib/git/proto/init.proto
@@ -0,0 +1,46 @@
+syntax = "proto3";
+
+package git.v1;
+
+// Mirrors: cmd/init.rs — InitRepositoriesParams
+message InitRepoParams {
+  string namespace = 1;
+  string repo_name = 2;
+  string default_branch = 3;
+  optional string description = 4;
+  bool initialize_with_readme = 5;
+  bool enable_lfs = 6;
+}
+
+message InitBareRequest {
+  string storage_root = 1;
+  InitRepoParams params = 2;
+}
+
+message InitBareResponse {
+  string storage_path = 1;
+}
+
+message SetDefaultBranchRequest {
+  string repo_id = 1;
+  string branch_name = 2;
+}
+
+message SetDefaultBranchResponse {}
+
+message CloneBareRequest {
+  string storage_root = 1;
+  string source_url = 2;
+  string namespace = 3;
+  string repo_name = 4;
+}
+
+message CloneBareResponse {
+  string storage_path = 1;
+}
+
+service InitService {
+  rpc InitBare(InitBareRequest) returns (InitBareResponse);
+  rpc SetDefaultBranch(SetDefaultBranchRequest) returns (SetDefaultBranchResponse);
+  rpc CloneBare(CloneBareRequest) returns (CloneBareResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/merge.proto b/lib/git/proto/merge.proto
new file mode 100644
index 0000000..cdbdd17
--- /dev/null
+++ b/lib/git/proto/merge.proto
@@ -0,0 +1,170 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/merge/mod.rs — MergeAnalysisResult
+message MergeAnalysisResult {
+  bool is_none = 1;
+  bool is_normal = 2;
+  bool is_up_to_date = 3;
+  bool is_fast_forward = 4;
+  bool is_unborn = 5;
+}
+
+// Mirrors: cmd/merge/mod.rs — MergePreferenceResult
+message MergePreferenceResult {
+  bool is_none = 1;
+  bool is_no_fast_forward = 2;
+  bool is_fastforward_only = 3;
+}
+
+// Mirrors: cmd/merge/mod.rs — MergeOptions
+message MergeOptions {
+  bool find_renames = 1;
+  bool fail_on_conflict = 2;
+  bool skip_reuc = 3;
+  bool no_recursive = 4;
+  uint32 rename_threshold = 5;
+  uint32 target_limit = 6;
+  uint32 recursion_limit = 7;
+}
+
+// Mirrors: cmd/merge/merge_commit.rs — MergeCommitParams
+message MergeCommitParams {
+  ObjectId their_commit = 1;
+  CommitSignature author = 2;
+  CommitSignature committer = 3;
+  string message = 4;
+  optional string update_ref = 5;
+  optional MergeOptions options = 6;
+}
+
+// Mirrors: cmd/merge/merge_tree.rs — MergeTreeResult
+message MergeTreeResult {
+  ObjectId tree_id = 1;
+  bool has_conflicts = 2;
+}
+
+// Mirrors: cmd/merge/squash_commit.rs — SquashCommitParams
+message SquashCommitParams {
+  ObjectId their_commit = 1;
+  optional MergeOptions options = 2;
+}
+
+message MergeBaseRequest {
+  string repo_id = 1;
+  ObjectId oid_a = 2;
+  ObjectId oid_b = 3;
+}
+
+message MergeBaseResponse {
+  ObjectId base_oid = 1;
+}
+
+message MergeBaseManyRequest {
+  string repo_id = 1;
+  repeated ObjectId oids = 2;
+}
+
+message MergeBaseManyResponse {
+  ObjectId base_oid = 1;
+}
+
+message MergeBaseOctopusRequest {
+  string repo_id = 1;
+  repeated ObjectId oids = 2;
+}
+
+message MergeBaseOctopusResponse {
+  ObjectId base_oid = 1;
+}
+
+message MergeAnalysisRequest {
+  string repo_id = 1;
+  ObjectId oid_a = 2;
+  ObjectId oid_b = 3;
+}
+
+message MergeAnalysisResponse {
+  MergeAnalysisResult analysis = 1;
+  MergePreferenceResult preference = 2;
+}
+
+message MergeAnalysisForRefRequest {
+  string repo_id = 1;
+  string ref_name = 2;
+  ObjectId oid_a = 3;
+  ObjectId oid_b = 4;
+}
+
+message MergeAnalysisForRefResponse {
+  MergeAnalysisResult analysis = 1;
+  MergePreferenceResult preference = 2;
+}
+
+message MergeIsConflictedRequest {
+  string repo_id = 1;
+}
+
+message MergeIsConflictedResponse {
+  bool is_conflicted = 1;
+}
+
+message MergeheadListRequest {
+  string repo_id = 1;
+}
+
+message MergeheadListResponse {
+  repeated ObjectId oids = 1;
+}
+
+message MergeTreeRequest {
+  string repo_id = 1;
+  ObjectId ours = 2;
+  ObjectId theirs = 3;
+  optional MergeOptions options = 4;
+}
+
+message MergeTreeResponse {
+  MergeTreeResult result = 1;
+}
+
+message MergeCommitRequest {
+  string repo_id = 1;
+  MergeCommitParams params = 2;
+}
+
+message MergeCommitResponse {
+  ObjectId oid = 1;
+}
+
+message SquashCommitRequest {
+  string repo_id = 1;
+  SquashCommitParams params = 2;
+}
+
+message SquashCommitResponse {
+  ObjectId oid = 1;
+}
+
+message MergeAbortRequest {
+  string repo_id = 1;
+}
+
+message MergeAbortResponse {}
+
+service MergeService {
+  rpc MergeBase(MergeBaseRequest) returns (MergeBaseResponse);
+  rpc MergeBaseMany(MergeBaseManyRequest) returns (MergeBaseManyResponse);
+  rpc MergeBaseOctopus(MergeBaseOctopusRequest) returns (MergeBaseOctopusResponse);
+  rpc MergeAnalysis(MergeAnalysisRequest) returns (MergeAnalysisResponse);
+  rpc MergeAnalysisForRef(MergeAnalysisForRefRequest) returns (MergeAnalysisForRefResponse);
+  rpc MergeIsConflicted(MergeIsConflictedRequest) returns (MergeIsConflictedResponse);
+  rpc MergeheadList(MergeheadListRequest) returns (MergeheadListResponse);
+  rpc MergeTree(MergeTreeRequest) returns (MergeTreeResponse);
+  rpc MergeCommit(MergeCommitRequest) returns (MergeCommitResponse);
+  rpc SquashCommit(SquashCommitRequest) returns (SquashCommitResponse);
+  rpc MergeAbort(MergeAbortRequest) returns (MergeAbortResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/tag.proto b/lib/git/proto/tag.proto
new file mode 100644
index 0000000..1a75bee
--- /dev/null
+++ b/lib/git/proto/tag.proto
@@ -0,0 +1,117 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/tag/mod.rs — TagItem
+message TagItem {
+  string name = 1;
+  ObjectId oid = 2;
+  ObjectId target = 3;
+  bool is_annotated = 4;
+  optional string message = 5;
+  optional string tagger = 6;
+  optional string tagger_email = 7;
+}
+
+// Mirrors: cmd/tag/mod.rs — TagSummary
+message TagSummary {
+  uint64 total_count = 1;
+}
+
+// Mirrors: cmd/tag/tag_init.rs — TagInitParams
+message TagInitParams {
+  string name = 1;
+  ObjectId target = 2;
+  optional string message = 3;
+  optional GitTagger tagger = 4;
+  bool force = 5;
+}
+
+// Mirrors: cmd/tag/tag_delete.rs — TagDeleteParams
+message TagDeleteParams {
+  string name = 1;
+}
+
+// Mirrors: cmd/tag/tag_rename.rs — TagRenameParams
+message TagRenameParams {
+  string old_name = 1;
+  string new_name = 2;
+  bool force = 3;
+}
+
+// Mirrors: cmd/tag/tag_upmsg.rs — TagUpdateMessageParams
+message TagUpdateMessageParams {
+  string name = 1;
+  string message = 2;
+  GitTagger tagger = 3;
+  bool force = 4;
+}
+
+message TagListRequest {
+  string repo_id = 1;
+}
+
+message TagListResponse {
+  repeated TagItem tags = 1;
+}
+
+message TagInfoRequest {
+  string repo_id = 1;
+  string name = 2;
+}
+
+message TagInfoResponse {
+  TagItem tag = 1;
+}
+
+message TagSummaryRequest {
+  string repo_id = 1;
+}
+
+message TagSummaryResponse {
+  TagSummary summary = 1;
+}
+
+message TagInitRequest {
+  string repo_id = 1;
+  TagInitParams params = 2;
+}
+
+message TagInitResponse {
+  ObjectId oid = 1;
+}
+
+message TagDeleteRequest {
+  string repo_id = 1;
+  TagDeleteParams params = 2;
+}
+
+message TagDeleteResponse {}
+
+message TagRenameRequest {
+  string repo_id = 1;
+  TagRenameParams params = 2;
+}
+
+message TagRenameResponse {}
+
+message TagUpdateMessageRequest {
+  string repo_id = 1;
+  TagUpdateMessageParams params = 2;
+}
+
+message TagUpdateMessageResponse {
+  ObjectId oid = 1;
+}
+
+service TagService {
+  rpc TagList(TagListRequest) returns (TagListResponse);
+  rpc TagInfo(TagInfoRequest) returns (TagInfoResponse);
+  rpc TagSummary(TagSummaryRequest) returns (TagSummaryResponse);
+  rpc TagInit(TagInitRequest) returns (TagInitResponse);
+  rpc TagDelete(TagDeleteRequest) returns (TagDeleteResponse);
+  rpc TagRename(TagRenameRequest) returns (TagRenameResponse);
+  rpc TagUpdateMessage(TagUpdateMessageRequest) returns (TagUpdateMessageResponse);
+}
\ No newline at end of file
diff --git a/lib/git/proto/tree.proto b/lib/git/proto/tree.proto
new file mode 100644
index 0000000..ba39c54
--- /dev/null
+++ b/lib/git/proto/tree.proto
@@ -0,0 +1,80 @@
+syntax = "proto3";
+
+package git.v1;
+
+import "common.proto";
+
+// Mirrors: cmd/tree/mod.rs — TreeKind
+enum TreeKind {
+  TREE_KIND_BLOB = 0;
+  TREE_KIND_TREE = 1;
+  TREE_KIND_LFS_POINTER = 2;
+}
+
+// Mirrors: cmd/tree/mod.rs — TreeInfo
+message TreeInfo {
+  ObjectId oid = 1;
+  uint64 entry_count = 2;
+  bool is_empty = 3;
+}
+
+// Mirrors: cmd/tree/mod.rs — TreeEntry
+message TreeEntry {
+  string name = 1;
+  ObjectId oid = 2;
+  TreeKind kind = 3;
+  uint32 filemode = 4;
+  bool is_binary = 5;
+  bool is_lfs = 6;
+  string last_commit_message = 7;
+  string last_commit_time = 8;
+  string last_commit_author_name = 9;
+  string last_commit_author_email = 10;
+}
+
+message TreeEntriesRequest {
+  string repo_id = 1;
+  ObjectId oid = 2;
+  string base_path = 3;
+  bool last = 4;
+}
+
+message TreeEntriesResponse {
+  repeated TreeEntry entries = 1;
+}
+
+message TreeEntryByPathRequest {
+  string repo_id = 1;
+  ObjectId tree_oid = 2;
+  string path = 3;
+}
+
+message TreeEntryByPathResponse {
+  optional TreeEntry entry = 1;
+}
+
+message TreeEntryByPathFromCommitRequest {
+  string repo_id = 1;
+  ObjectId commit_oid = 2;
+  string path = 3;
+}
+
+message TreeEntryByPathFromCommitResponse {
+  optional TreeEntry entry = 1;
+}
+
+message ResolveTreeRequest {
+  string repo_id = 1;
+  ObjectId oid = 2;
+}
+
+message ResolveTreeResponse {
+  TreeInfo info = 1;
+}
+
+service TreeService {
+  rpc TreeEntries(TreeEntriesRequest) returns (TreeEntriesResponse);
+  rpc TreeEntryByPath(TreeEntryByPathRequest) returns (TreeEntryByPathResponse);
+  rpc TreeEntryByPathFromCommit(TreeEntryByPathFromCommitRequest) returns (TreeEntryByPathFromCommitResponse);
+  rpc ResolveTree(ResolveTreeRequest) returns (ResolveTreeResponse);
+}
\ No newline at end of file
diff --git a/lib/git/role.rs b/lib/git/role.rs
new file mode 100644
index 0000000..0c46ecf
--- /dev/null
+++ b/lib/git/role.rs
@@ -0,0 +1,162 @@
+use model::{
+    repos::{repo::RepoModel, repo_history_name::RepoHistoryNameModel},
+    users::user::UserModel,
+    workspace::{
+        wk_history_name::WkHistoryNameModel, wk_member::WkMemberModel,
+        workspace::WorkspaceModel,
+    },
+};
+use uuid::Uuid;
+
+use crate::{
+    AppGitState,
+    errors::{GitError, GitResult},
+};
+
+#[derive(Clone, Debug)]
+pub struct DbRepoStatus {
+    pub repo: RepoModel,
+    pub wk: WorkspaceModel,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum MemberRole {
+    Owner,
+    Admin,
+    Member,
+}
+
+impl MemberRole {
+    pub fn can_write(self) -> bool {
+        matches!(self, Self::Owner | Self::Admin)
+    }
+}
+
+impl AppGitState {
+    pub async fn repo(
+        &self,
+        wk_name: String,
+        repo_name: String,
+    ) -> GitResult<DbRepoStatus> {
+        let wk = self.resolve_wk(&wk_name).await?;
+        let repo = self.resolve_repo(wk.id, &repo_name).await?;
+
+        Ok(DbRepoStatus { repo, wk })
+    }
+
+    pub async fn member_check(
+        &self,
+        status: &DbRepoStatus,
+        user: &UserModel,
+    ) -> GitResult<Option<MemberRole>> {
+        self.member_check_by_user_id(status, user.id).await
+    }
+
+    pub async fn member_check_by_user_id(
+        &self,
+        status: &DbRepoStatus,
+        user_id: Uuid,
+    ) -> GitResult<Option<MemberRole>> {
+        let member = db::sqlx::query_as::<_, WkMemberModel>(
+            "SELECT wk, \"user\", owner, admin, join_at, leave_at \
+             FROM wk_member \
+             WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+        )
+        .bind(status.wk.id)
+        .bind(user_id)
+        .fetch_optional(self.db.reader())
+        .await?;
+
+        Ok(member.map(|member| {
+            if member.owner {
+                MemberRole::Owner
+            } else if member.admin {
+                MemberRole::Admin
+            } else {
+                MemberRole::Member
+            }
+        }))
+    }
+
+    async fn resolve_wk(&self, name: &str) -> GitResult<WorkspaceModel> {
+        if let Some(wk) = db::sqlx::query_as::<_, WorkspaceModel>(
+            "SELECT id, name, description, avatar_url, created_at \
+             FROM workspace \
+             WHERE name = $1",
+        )
+        .bind(&name)
+        .fetch_optional(self.db.reader())
+        .await?
+        {
+            return Ok(wk);
+        }
+
+        let Some(history) = db::sqlx::query_as::<_, WkHistoryNameModel>(
+            "SELECT id, wk, name, changed_by, created_at \
+             FROM wk_history_name \
+             WHERE name = $1 \
+             ORDER BY created_at DESC \
+             LIMIT 1",
+        )
+        .bind(&name)
+        .fetch_optional(self.db.reader())
+        .await?
+        else {
+            return Err(GitError::RepoNotFound);
+        };
+
+        db::sqlx::query_as::<_, WorkspaceModel>(
+            "SELECT id, name, description, avatar_url, created_at \
+             FROM workspace \
+             WHERE id = $1",
+        )
+        .bind(history.wk)
+        .fetch_optional(self.db.reader())
+        .await?
+        .ok_or(GitError::RepoNotFound)
+    }
+
+    async fn resolve_repo(&self, wk: Uuid, name: &str) -> GitResult<RepoModel> {
+        if let Some(repo) = db::sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+                    is_archived, is_template, is_mirror, created_by, created_at, updated_at, deleted_at \
+             FROM repo \
+             WHERE wk = $1 AND name = $2 AND deleted_at IS NULL",
+        )
+        .bind(wk)
+        .bind(&name)
+        .fetch_optional(self.db.reader())
+        .await?
+        {
+            return Ok(repo);
+        }
+
+        let Some(history) = db::sqlx::query_as::<_, RepoHistoryNameModel>(
+            "SELECT h.id, h.repo, h.name, h.changed_by, h.created_at \
+             FROM repo_history_name h \
+             INNER JOIN repo r ON h.repo = r.id \
+             WHERE h.name = $1 AND r.wk = $2 AND r.deleted_at IS NULL \
+             ORDER BY h.created_at DESC \
+             LIMIT 1",
+        )
+        .bind(&name)
+        .bind(wk)
+        .fetch_optional(self.db.reader())
+        .await?
+        else {
+            return Err(GitError::RepoNotFound);
+        };
+
+        db::sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+                    is_archived, is_template, is_mirror, created_by, created_at, updated_at, deleted_at \
+             FROM repo \
+             WHERE id = $1 AND wk = $2 AND deleted_at IS NULL",
+        )
+        .bind(history.repo)
+        .bind(wk)
+        .fetch_optional(self.db.reader())
+        .await?
+        .ok_or(GitError::RepoNotFound)
+    }
+}
diff --git a/lib/git/rpc/archive.rs b/lib/git/rpc/archive.rs
new file mode 100644
index 0000000..17d92c6
--- /dev/null
+++ b/lib/git/rpc/archive.rs
@@ -0,0 +1,46 @@
+use std::sync::Arc;
+
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct ArchiveServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+}
+
+#[tonic::async_trait]
+impl p::archive_service_server::ArchiveService for ArchiveServiceImpl {
+    async fn archive_tar(
+        &self,
+        req: Request<p::ArchiveTarRequest>,
+    ) -> Result<Response<p::ArchiveTarResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let options = inner.options.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.archive_tar(options))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::ArchiveTarResponse { data: result.bytes }))
+    }
+
+    async fn archive_zip(
+        &self,
+        req: Request<p::ArchiveZipRequest>,
+    ) -> Result<Response<p::ArchiveZipResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let options = inner.options.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.archive_zip(options))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::ArchiveZipResponse { data: result.bytes }))
+    }
+}
diff --git a/lib/git/rpc/blame.rs b/lib/git/rpc/blame.rs
new file mode 100644
index 0000000..17e9004
--- /dev/null
+++ b/lib/git/rpc/blame.rs
@@ -0,0 +1,130 @@
+use std::sync::Arc;
+
+use cache::AppCache;
+use tokio_stream::wrappers::ReceiverStream;
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct BlameServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+    pub cache: AppCache,
+}
+
+type BlameStream = ReceiverStream<Result<p::CommitBlameHunk, Status>>;
+
+#[tonic::async_trait]
+impl p::blame_service_server::BlameService for BlameServiceImpl {
+    type BlameStreamStream = BlameStream;
+
+    async fn blame_file(
+        &self,
+        req: Request<p::BlameFileRequest>,
+    ) -> Result<Response<p::BlameFileResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let rev_str = inner.rev.unwrap_or_default();
+        let path = inner.path.clone();
+        let cache_key = format!("git:rpc:cache:blame:file:{}:{}:{}", repo_id, path, rev_str);
+
+        if let Ok(Some(cached)) = self.cache.get::<p::BlameFileResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let oid = crate::cmd::oid::ObjectId::new(&rev_str);
+        let opts = inner.options.map(Into::into);
+        let result = tokio::task::spawn_blocking(move || {
+            bare.blame_file(oid, &path, opts)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        let resp = p::BlameFileResponse {
+            hunks: result.into_iter().map(Into::into).collect(),
+        };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    async fn blame_stream(
+        &self,
+        req: Request<p::BlameFileRequest>,
+    ) -> Result<Response<BlameStream>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let rev_str = inner.rev.unwrap_or_default();
+        let oid = crate::cmd::oid::ObjectId::new(&rev_str);
+        let path = inner.path.clone();
+        let opts = inner.options.map(Into::into);
+        let (tx, rx) = tokio::sync::mpsc::channel(128);
+        tokio::task::spawn_blocking(move || {
+            let result = bare.blame_file(oid, &path, opts);
+            match result {
+                Ok(hunks) => {
+                    for hunk in hunks {
+                        if tx.blocking_send(Ok(hunk.into())).is_err() {
+                            break;
+                        }
+                    }
+                }
+                Err(e) => {
+                    let _ = tx.blocking_send(Err(to_status(e)));
+                }
+            }
+        });
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+
+    async fn blame_hunk(
+        &self,
+        req: Request<p::BlameHunkRequest>,
+    ) -> Result<Response<p::BlameHunkResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let rev_str = inner.rev.unwrap_or_default();
+        let oid = crate::cmd::oid::ObjectId::new(&rev_str);
+        let path = inner.path.clone();
+        let line_on = inner.start_line as usize;
+        let result = tokio::task::spawn_blocking(move || {
+            bare.blame_hunk(&oid, &path, line_on)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::BlameHunkResponse {
+            hunks: vec![result.into()],
+        }))
+    }
+
+    async fn blame_lines(
+        &self,
+        req: Request<p::BlameLinesRequest>,
+    ) -> Result<Response<p::BlameLinesResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let rev_str = inner.rev.unwrap_or_default();
+        let oid = crate::cmd::oid::ObjectId::new(&rev_str);
+        let path = inner.path.clone();
+        let opts = Some(crate::cmd::blame::BlameOptions {
+            min_line: Some(inner.start_line as usize),
+            max_line: Some(inner.end_line as usize),
+            track_copies_same_file: false,
+            track_copies_same_commit_moves: false,
+            ignore_whitespace: false,
+        });
+        let result = tokio::task::spawn_blocking(move || {
+            bare.blame_lines(oid, &path, opts)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::BlameLinesResponse {
+            lines: result.into_iter().map(Into::into).collect(),
+        }))
+    }
+}
diff --git a/lib/git/rpc/blob.rs b/lib/git/rpc/blob.rs
new file mode 100644
index 0000000..cd40309
--- /dev/null
+++ b/lib/git/rpc/blob.rs
@@ -0,0 +1,159 @@
+use std::sync::Arc;
+
+use cache::AppCache;
+use tokio_stream::wrappers::ReceiverStream;
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct BlobServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+    pub cache: AppCache,
+}
+
+type BlobChunkStream = ReceiverStream<Result<p::BlobChunk, Status>>;
+
+#[tonic::async_trait]
+impl p::blob_service_server::BlobService for BlobServiceImpl {
+    async fn blob_load(
+        &self,
+        req: Request<p::BlobLoadRequest>,
+    ) -> Result<Response<p::BlobLoadResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let oid_str = inner.id.clone().map(|o| o.value).unwrap_or_default();
+        let path = inner.path.clone();
+        let cache_key = format!("git:rpc:cache:blob:load:{}:{}:{}", repo_id, oid_str, path);
+
+        if let Ok(Some(cached)) = self.cache.get::<p::BlobLoadResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let params = crate::cmd::blob::BlobLoadParams {
+            id: inner.id.unwrap_or_default().into(),
+            path: inner.path.clone(),
+        };
+        let params_clone = params.clone();
+        let result =
+            tokio::task::spawn_blocking(move || bare.blob_load(&params_clone))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        let resp = p::BlobLoadResponse { blob: result.blob };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    async fn blob_size(
+        &self,
+        req: Request<p::BlobSizeRequest>,
+    ) -> Result<Response<p::BlobSizeResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = crate::cmd::blob::BlobSizeParams {
+            id: inner.id.unwrap_or_default().into(),
+            path: inner.path.clone(),
+        };
+        let result =
+            tokio::task::spawn_blocking(move || bare.blob_size(&params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BlobSizeResponse { size: result }))
+    }
+
+    async fn blob_exists(
+        &self,
+        req: Request<p::BlobExistsRequest>,
+    ) -> Result<Response<p::BlobExistsResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let oid: crate::cmd::oid::ObjectId =
+            inner.id.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || bare.blob_exists(oid))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::BlobExistsResponse { exists: result }))
+    }
+
+    async fn blob_is_binary(
+        &self,
+        req: Request<p::BlobIsBinaryRequest>,
+    ) -> Result<Response<p::BlobIsBinaryResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let oid_str = inner.id.clone().map(|o| o.value).unwrap_or_default();
+        let cache_key = format!("git:rpc:cache:blob:binary:{}:{}", repo_id, oid_str);
+
+        if let Ok(Some(cached)) = self.cache.get::<p::BlobIsBinaryResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let oid: crate::cmd::oid::ObjectId =
+            inner.id.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.blob_is_binary(oid))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        let resp = p::BlobIsBinaryResponse { is_binary: result };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    async fn blob_upload(
+        &self,
+        req: Request<p::BlobUploadRequest>,
+    ) -> Result<Response<p::BlobUploadResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = crate::cmd::blob::BlobUploadParams {
+            blob: inner.blob.clone(),
+            path: inner.path.clone(),
+        };
+        let result =
+            tokio::task::spawn_blocking(move || bare.blob_upload(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BlobUploadResponse {
+            id: Some(result.id.into()),
+        }))
+    }
+
+    type BlobChunkStreamStream = BlobChunkStream;
+
+    async fn blob_chunk_stream(
+        &self,
+        req: Request<p::BlobChunkRequest>,
+    ) -> Result<Response<BlobChunkStream>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let param = crate::cmd::blob::BlobChunkParam {
+            path: inner.path.clone(),
+            oid: inner.oid.unwrap_or_default().into(),
+            size: inner.size as usize,
+            offset: inner.offset as usize,
+        };
+        let (tx, rx) = tokio::sync::mpsc::channel(4);
+        tokio::task::spawn_blocking(move || {
+            let result = bare.blob_chunk(param);
+            match result {
+                Ok(chunk) => {
+                    let _ = tx.blocking_send(Ok(chunk.into()));
+                }
+                Err(e) => {
+                    let _ = tx.blocking_send(Err(to_status(e)));
+                }
+            }
+        });
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+}
diff --git a/lib/git/rpc/branch.rs b/lib/git/rpc/branch.rs
new file mode 100644
index 0000000..6bf1c48
--- /dev/null
+++ b/lib/git/rpc/branch.rs
@@ -0,0 +1,160 @@
+use std::sync::Arc;
+
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct BranchServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+}
+
+#[tonic::async_trait]
+impl p::branch_service_server::BranchService for BranchServiceImpl {
+    async fn branch_list(
+        &self,
+        req: Request<p::BranchListRequest>,
+    ) -> Result<Response<p::BranchListResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result =
+            tokio::task::spawn_blocking(move || bare.branch_list_all())
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BranchListResponse {
+            branches: result.into_iter().map(Into::into).collect(),
+        }))
+    }
+
+    async fn branch_info(
+        &self,
+        req: Request<p::BranchInfoRequest>,
+    ) -> Result<Response<p::BranchInfoResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let branch = inner.branch.clone();
+        let result =
+            tokio::task::spawn_blocking(move || bare.branch_info(branch))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BranchInfoResponse {
+            branch: Some(result.into()),
+        }))
+    }
+
+    async fn branch_summary(
+        &self,
+        req: Request<p::BranchSummaryRequest>,
+    ) -> Result<Response<p::BranchSummaryResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result = tokio::task::spawn_blocking(move || bare.branch_summary())
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::BranchSummaryResponse {
+            summary: Some(result.into()),
+        }))
+    }
+
+    async fn branch_head(
+        &self,
+        req: Request<p::BranchHeadRequest>,
+    ) -> Result<Response<p::BranchHeadResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result =
+            tokio::task::spawn_blocking(move || bare.branch_head_name())
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BranchHeadResponse { head_name: result }))
+    }
+
+    async fn branch_ahead_behind(
+        &self,
+        req: Request<p::BranchAheadBehindRequest>,
+    ) -> Result<Response<p::BranchAheadBehindResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let branch = inner.local_branch.clone();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.branch_ahead_behind(branch)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::BranchAheadBehindResponse {
+            ahead: if result { 1 } else { 0 },
+            behind: 0,
+        }))
+    }
+
+    async fn branch_upstream(
+        &self,
+        req: Request<p::BranchUpstreamRequest>,
+    ) -> Result<Response<p::BranchUpstreamResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let branch = inner.branch.clone();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.branch_upstream_name(branch)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::BranchUpstreamResponse {
+            upstream_name: result.unwrap_or_default(),
+        }))
+    }
+
+    async fn branch_fork(
+        &self,
+        req: Request<p::BranchForkRequest>,
+    ) -> Result<Response<p::BranchForkResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let _result =
+            tokio::task::spawn_blocking(move || bare.branch_fork(&params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BranchForkResponse {}))
+    }
+
+    async fn branch_delete(
+        &self,
+        req: Request<p::BranchDeleteRequest>,
+    ) -> Result<Response<p::BranchDeleteResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let _result =
+            tokio::task::spawn_blocking(move || bare.branch_delete(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BranchDeleteResponse {}))
+    }
+
+    async fn branch_rename(
+        &self,
+        req: Request<p::BranchRenameRequest>,
+    ) -> Result<Response<p::BranchRenameResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let _result =
+            tokio::task::spawn_blocking(move || bare.branch_rename(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::BranchRenameResponse {}))
+    }
+}
diff --git a/lib/git/rpc/commit.rs b/lib/git/rpc/commit.rs
new file mode 100644
index 0000000..83edad2
--- /dev/null
+++ b/lib/git/rpc/commit.rs
@@ -0,0 +1,291 @@
+use std::sync::Arc;
+
+use cache::AppCache;
+use tokio_stream::wrappers::ReceiverStream;
+use tonic::{Request, Response, Status};
+use uuid::Uuid;
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+use crate::sync::ReceiveSyncService;
+
+pub struct CommitServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+    pub cache: AppCache,
+    pub sync: ReceiveSyncService,
+}
+
+type CommitHistoryStream = ReceiverStream<Result<p::CommitMeta, Status>>;
+
+#[tonic::async_trait]
+impl p::commit_service_server::CommitService for CommitServiceImpl {
+    async fn commit_info(
+        &self,
+        req: Request<p::CommitInfoRequest>,
+    ) -> Result<Response<p::CommitInfoResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let oid = inner.oid.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || bare.commit_info(oid))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::CommitInfoResponse {
+            commit: Some(result.into()),
+        }))
+    }
+
+    async fn commit_history(
+        &self,
+        req: Request<p::CommitHistoryRequest>,
+    ) -> Result<Response<p::CommitHistoryResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let cache_key = format!(
+            "git:rpc:cache:commit:history:{}:{}:{}:{}:{}",
+            repo_id, inner.limit, inner.skip, inner.sort, inner.branch.as_deref().unwrap_or("")
+        );
+
+        if let Ok(Some(cached)) = self.cache.get::<p::CommitHistoryResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let params = crate::cmd::commit::CommitWalkParams {
+            start_oids: vec![],
+            hide_oids: vec![],
+            limit: if inner.limit > 0 { Some(inner.limit as usize) } else { None },
+            skip: inner.skip as usize,
+            first_parent: false,
+            sort: inner.sort.into(),
+            branch: inner.branch.clone(),
+        };
+        let result =
+            tokio::task::spawn_blocking(move || bare.commit_history(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        let resp = p::CommitHistoryResponse {
+            commits: result.into_iter().map(Into::into).collect(),
+        };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    type CommitHistoryStreamStream = CommitHistoryStream;
+
+    async fn commit_history_stream(
+        &self,
+        req: Request<p::CommitHistoryRequest>,
+    ) -> Result<Response<CommitHistoryStream>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = crate::cmd::commit::CommitWalkParams {
+            start_oids: vec![],
+            hide_oids: vec![],
+            limit: if inner.limit > 0 { Some(inner.limit as usize) } else { None },
+            skip: inner.skip as usize,
+            first_parent: false,
+            sort: inner.sort.into(),
+            branch: inner.branch.clone(),
+        };
+        let (tx, rx) = tokio::sync::mpsc::channel(128);
+        tokio::task::spawn_blocking(move || {
+            let result = bare.commit_history(params);
+            match result {
+                Ok(commits) => {
+                    for c in commits {
+                        if tx.blocking_send(Ok(c.into())).is_err() {
+                            break;
+                        }
+                    }
+                }
+                Err(e) => {
+                    let _ = tx.blocking_send(Err(to_status(e)));
+                }
+            }
+        });
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+
+    async fn commit_summary(
+        &self,
+        req: Request<p::CommitSummaryRequest>,
+    ) -> Result<Response<p::CommitSummaryResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let cache_key = format!("git:rpc:cache:commit:summary:{}", repo_id);
+
+        if let Ok(Some(cached)) = self.cache.get::<p::CommitSummaryResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let result = tokio::task::spawn_blocking(move || bare.commit_summary())
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        let resp = p::CommitSummaryResponse { summary: Some(result.into()) };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    async fn commit_walk(
+        &self,
+        req: Request<p::CommitWalkRequest>,
+    ) -> Result<Response<p::CommitWalkResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.commit_walk(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::CommitWalkResponse {
+            commits: result.into_iter().map(Into::into).collect(),
+        }))
+    }
+
+    async fn commit_refs(
+        &self,
+        req: Request<p::CommitRefsRequest>,
+    ) -> Result<Response<p::CommitRefsResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result = tokio::task::spawn_blocking(move || {
+            let repo = bare.gix_repo()?;
+            let head_id = repo.head_id()?.detach();
+            let oid = crate::cmd::oid::ObjectId::new(head_id.to_hex().to_string());
+            bare.commit_refs(oid)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::CommitRefsResponse {
+            refs: result.into_iter().map(Into::into).collect(),
+        }))
+    }
+
+    async fn commit_prefix(
+        &self,
+        req: Request<p::CommitPrefixRequest>,
+    ) -> Result<Response<p::CommitPrefixResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let prefix = inner.prefix.clone();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.commit_oid_from_prefix(&prefix)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::CommitPrefixResponse {
+            oid: Some(result.into()),
+        }))
+    }
+
+    async fn commit_exists(
+        &self,
+        req: Request<p::CommitExistsRequest>,
+    ) -> Result<Response<p::CommitExistsResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let oid: crate::cmd::oid::ObjectId =
+            inner.oid.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.commit_exists(oid))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::CommitExistsResponse { exists: result }))
+    }
+
+    async fn cherry_pick(
+        &self,
+        req: Request<p::CherryPickRequest>,
+    ) -> Result<Response<p::CherryPickResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.commit_pick(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+
+        if let Ok(repo_uid) = Uuid::parse_str(&repo_id) {
+            self.sync.send(crate::sync::RepoReceiveSyncTask { repo_uid }).await;
+        }
+
+        Ok(Response::new(p::CherryPickResponse {
+            oid: Some(result.into()),
+        }))
+    }
+
+    async fn cherry_pick_sequence(
+        &self,
+        req: Request<p::CherryPickSequenceRequest>,
+    ) -> Result<Response<p::CherryPickSequenceResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.commit_cherry_pick_sequence(params)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+
+        if let Ok(repo_uid) = Uuid::parse_str(&repo_id) {
+            self.sync.send(crate::sync::RepoReceiveSyncTask { repo_uid }).await;
+        }
+
+        Ok(Response::new(p::CherryPickSequenceResponse {
+            oid: Some(result.into()),
+        }))
+    }
+
+    async fn create_commit(
+        &self,
+        req: Request<p::CreateCommitRequest>,
+    ) -> Result<Response<p::CreateCommitResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = crate::cmd::commit::CreateCommitParams {
+            branch: inner.branch.clone(),
+            message: inner.message.clone(),
+            author_name: inner.author_name.clone(),
+            author_email: inner.author_email.clone(),
+            committer_name: inner.committer_name.clone(),
+            committer_email: inner.committer_email.clone(),
+            files: inner
+                .files
+                .into_iter()
+                .map(|f| crate::cmd::commit::FileChange {
+                    path: f.path,
+                    content: f.content,
+                })
+                .collect(),
+        };
+        let result = tokio::task::spawn_blocking(move || bare.commit_create(params))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+
+        // Trigger sync after write
+        if let Ok(repo_uid) = Uuid::parse_str(&repo_id) {
+            self.sync.send(crate::sync::RepoReceiveSyncTask { repo_uid }).await;
+        }
+
+        Ok(Response::new(p::CreateCommitResponse {
+            oid: Some(result.into()),
+        }))
+    }
+}
diff --git a/lib/git/rpc/convert.rs b/lib/git/rpc/convert.rs
new file mode 100644
index 0000000..44020a5
--- /dev/null
+++ b/lib/git/rpc/convert.rs
@@ -0,0 +1,704 @@
+use crate::{cmd::oid::ObjectId, rpc::proto as p};
+
+impl From<ObjectId> for p::ObjectId {
+    fn from(oid: ObjectId) -> Self {
+        p::ObjectId { value: oid.0 }
+    }
+}
+
+impl From<p::ObjectId> for ObjectId {
+    fn from(oid: p::ObjectId) -> Self {
+        ObjectId::new(&oid.value)
+    }
+}
+
+impl From<&ObjectId> for p::ObjectId {
+    fn from(oid: &ObjectId) -> Self {
+        p::ObjectId {
+            value: oid.0.clone(),
+        }
+    }
+}
+
+impl From<crate::cmd::commit::CommitSignature> for p::CommitSignature {
+    fn from(sig: crate::cmd::commit::CommitSignature) -> Self {
+        p::CommitSignature {
+            name: sig.name,
+            email: sig.email,
+            time_secs: sig.time_secs,
+            offset_minutes: sig.offset_minutes,
+        }
+    }
+}
+
+impl From<p::CommitSignature> for crate::cmd::commit::CommitSignature {
+    fn from(sig: p::CommitSignature) -> Self {
+        crate::cmd::commit::CommitSignature {
+            name: sig.name,
+            email: sig.email,
+            time_secs: sig.time_secs,
+            offset_minutes: sig.offset_minutes,
+        }
+    }
+}
+
+impl From<crate::cmd::tagger::GitTagger> for p::GitTagger {
+    fn from(t: crate::cmd::tagger::GitTagger) -> Self {
+        p::GitTagger {
+            name: t.name,
+            email: t.email,
+        }
+    }
+}
+
+impl From<p::GitTagger> for crate::cmd::tagger::GitTagger {
+    fn from(t: p::GitTagger) -> Self {
+        crate::cmd::tagger::GitTagger {
+            name: t.name,
+            email: t.email,
+        }
+    }
+}
+
+impl From<crate::cmd::commit::CommitMeta> for p::CommitMeta {
+    fn from(c: crate::cmd::commit::CommitMeta) -> Self {
+        p::CommitMeta {
+            oid: Some(c.oid.into()),
+            message: c.message,
+            summary: c.summary,
+            author: Some(c.author.into()),
+            committer: Some(c.committer.into()),
+            tree_id: Some(c.tree_id.into()),
+            parent_ids: c.parent_ids.into_iter().map(Into::into).collect(),
+            encoding: c.encoding,
+        }
+    }
+}
+
+impl From<crate::cmd::commit::CommitRefInfo> for p::CommitRefInfo {
+    fn from(r: crate::cmd::commit::CommitRefInfo) -> Self {
+        p::CommitRefInfo {
+            name: r.name,
+            target: Some(r.target.into()),
+            is_remote: r.is_remote,
+            is_tag: r.is_tag,
+        }
+    }
+}
+
+impl From<crate::cmd::commit::CommitSummary> for p::CommitSummary {
+    fn from(s: crate::cmd::commit::CommitSummary) -> Self {
+        p::CommitSummary {
+            head: s.head.map(Into::into),
+            count: s.count as u64,
+        }
+    }
+}
+
+impl From<crate::cmd::commit::CommitWalkSort> for p::CommitWalkSort {
+    fn from(s: crate::cmd::commit::CommitWalkSort) -> Self {
+        match s {
+            crate::cmd::commit::CommitWalkSort::None => p::CommitWalkSort::None,
+            crate::cmd::commit::CommitWalkSort::Topological => {
+                p::CommitWalkSort::Topological
+            }
+            crate::cmd::commit::CommitWalkSort::Time => p::CommitWalkSort::Time,
+            crate::cmd::commit::CommitWalkSort::Reverse => {
+                p::CommitWalkSort::Reverse
+            }
+        }
+    }
+}
+
+impl From<p::CommitWalkSort> for crate::cmd::commit::CommitWalkSort {
+    fn from(s: p::CommitWalkSort) -> Self {
+        match s {
+            p::CommitWalkSort::None => crate::cmd::commit::CommitWalkSort::None,
+            p::CommitWalkSort::Topological => {
+                crate::cmd::commit::CommitWalkSort::Topological
+            }
+            p::CommitWalkSort::Time => crate::cmd::commit::CommitWalkSort::Time,
+            p::CommitWalkSort::Reverse => {
+                crate::cmd::commit::CommitWalkSort::Reverse
+            }
+        }
+    }
+}
+
+impl From<i32> for crate::cmd::commit::CommitWalkSort {
+    fn from(val: i32) -> Self {
+        let proto_sort: p::CommitWalkSort =
+            p::CommitWalkSort::try_from(val).unwrap_or(p::CommitWalkSort::Time);
+        proto_sort.into()
+    }
+}
+
+impl From<p::CommitWalkParams> for crate::cmd::commit::CommitWalkParams {
+    fn from(p: p::CommitWalkParams) -> Self {
+        crate::cmd::commit::CommitWalkParams {
+            start_oids: p.start_oids.into_iter().map(Into::into).collect(),
+            hide_oids: p.hide_oids.into_iter().map(Into::into).collect(),
+            limit: p.limit.map(|l| l as usize),
+            skip: p.skip as usize,
+            first_parent: p.first_parent,
+            sort: p.sort.into(),
+            branch: None,
+        }
+    }
+}
+
+impl From<p::CommitCherryPickParams>
+    for crate::cmd::commit::CommitCherryPickParams
+{
+    fn from(p: p::CommitCherryPickParams) -> Self {
+        crate::cmd::commit::CommitCherryPickParams {
+            cherrypick_oid: p.cherrypick_oid.unwrap_or_default().into(),
+            author: p.author.unwrap_or_default().into(),
+            committer: p.committer.unwrap_or_default().into(),
+            message: p.message,
+            mainline: p.mainline,
+            update_ref: p.update_ref,
+        }
+    }
+}
+
+impl From<p::CommitCherryPickSequence>
+    for crate::cmd::commit::CommitCherryPickSequence
+{
+    fn from(p: p::CommitCherryPickSequence) -> Self {
+        crate::cmd::commit::CommitCherryPickSequence {
+            cherrypick_oids: p
+                .cherrypick_oids
+                .into_iter()
+                .map(Into::into)
+                .collect(),
+            author: p.author.unwrap_or_default().into(),
+            committer: p.committer.unwrap_or_default().into(),
+            update_ref: p.update_ref,
+        }
+    }
+}
+
+impl From<crate::cmd::branch::BranchListItem> for p::BranchListItem {
+    fn from(b: crate::cmd::branch::BranchListItem) -> Self {
+        p::BranchListItem {
+            name: b.name,
+            oid: Some(b.oid.into()),
+            is_head: b.is_head,
+            is_remote: b.is_remote,
+            is_current: b.is_current,
+            upstream: b.upstream,
+        }
+    }
+}
+
+impl From<crate::cmd::branch::BranchSummary> for p::BranchSummary {
+    fn from(s: crate::cmd::branch::BranchSummary) -> Self {
+        p::BranchSummary {
+            local_count: s.local_count as u64,
+            remote_count: s.remote_count as u64,
+            all_count: s.all_count as u64,
+        }
+    }
+}
+
+impl From<p::BranchForkParams> for crate::cmd::branch::BranchForkParams {
+    fn from(p: p::BranchForkParams) -> Self {
+        crate::cmd::branch::BranchForkParams {
+            name: p.name,
+            oid: p.oid.unwrap_or_default().into(),
+            force: p.force,
+        }
+    }
+}
+
+impl From<p::BranchDeleteParams> for crate::cmd::branch::BranchDeleteParams {
+    fn from(p: p::BranchDeleteParams) -> Self {
+        crate::cmd::branch::BranchDeleteParams {
+            name: p.name,
+            force: p.force,
+        }
+    }
+}
+
+impl From<p::BranchReNameParams> for crate::cmd::branch::BranchReNameParams {
+    fn from(p: p::BranchReNameParams) -> Self {
+        crate::cmd::branch::BranchReNameParams {
+            old_branch: p.old_branch,
+            new_branch: p.new_branch,
+            force: p.force,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffDeltaStatus> for p::DiffDeltaStatus {
+    fn from(s: crate::cmd::diff::DiffDeltaStatus) -> Self {
+        match s {
+            crate::cmd::diff::DiffDeltaStatus::Unmodified => {
+                p::DiffDeltaStatus::Unmodified
+            }
+            crate::cmd::diff::DiffDeltaStatus::Added => {
+                p::DiffDeltaStatus::Added
+            }
+            crate::cmd::diff::DiffDeltaStatus::Deleted => {
+                p::DiffDeltaStatus::Deleted
+            }
+            crate::cmd::diff::DiffDeltaStatus::Modified => {
+                p::DiffDeltaStatus::Modified
+            }
+            crate::cmd::diff::DiffDeltaStatus::Renamed => {
+                p::DiffDeltaStatus::Renamed
+            }
+            crate::cmd::diff::DiffDeltaStatus::Copied => {
+                p::DiffDeltaStatus::Copied
+            }
+            crate::cmd::diff::DiffDeltaStatus::Typechange => {
+                p::DiffDeltaStatus::Typechange
+            }
+            crate::cmd::diff::DiffDeltaStatus::Conflicted => {
+                p::DiffDeltaStatus::Conflicted
+            }
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffFile> for p::DiffFile {
+    fn from(f: crate::cmd::diff::DiffFile) -> Self {
+        p::DiffFile {
+            oid: f.oid.map(Into::into),
+            path: f.path,
+            size: f.size,
+            is_binary: f.is_binary,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffHunk> for p::DiffHunk {
+    fn from(h: crate::cmd::diff::DiffHunk) -> Self {
+        p::DiffHunk {
+            old_start: h.old_start,
+            old_lines: h.old_lines,
+            new_start: h.new_start,
+            new_lines: h.new_lines,
+            header: h.header,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffLine> for p::DiffLine {
+    fn from(l: crate::cmd::diff::DiffLine) -> Self {
+        p::DiffLine {
+            content: l.content,
+            origin: l.origin.to_string(),
+            old_lineno: l.old_lineno,
+            new_lineno: l.new_lineno,
+            num_lines: l.num_lines,
+            content_offset: l.content_offset,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffDelta> for p::DiffDelta {
+    fn from(d: crate::cmd::diff::DiffDelta) -> Self {
+        let status_proto: p::DiffDeltaStatus = d.status.into();
+        p::DiffDelta {
+            status: status_proto as i32,
+            old_file: Some(d.old_file.into()),
+            new_file: Some(d.new_file.into()),
+            nfiles: d.nfiles as u32,
+            hunks: d.hunks.into_iter().map(Into::into).collect(),
+            lines: d.lines.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffStats> for p::DiffStats {
+    fn from(s: crate::cmd::diff::DiffStats) -> Self {
+        p::DiffStats {
+            files_changed: s.files_changed as u64,
+            insertions: s.insertions as u64,
+            deletions: s.deletions as u64,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::DiffResult> for p::DiffResult {
+    fn from(r: crate::cmd::diff::DiffResult) -> Self {
+        p::DiffResult {
+            stats: Some(r.stats.into()),
+            deltas: r.deltas.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<p::DiffOptions> for crate::cmd::diff::DiffOptions {
+    fn from(o: p::DiffOptions) -> Self {
+        crate::cmd::diff::DiffOptions {
+            context_lines: o.context_lines,
+            pathspec: o.pathspec,
+            ignore_whitespace: o.ignore_whitespace,
+            force_text: o.force_text,
+            reverse: o.reverse,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::SideBySideChangeType> for p::SideBySideChangeType {
+    fn from(t: crate::cmd::diff::SideBySideChangeType) -> Self {
+        match t {
+            crate::cmd::diff::SideBySideChangeType::Unchanged => {
+                p::SideBySideChangeType::Unchanged
+            }
+            crate::cmd::diff::SideBySideChangeType::Added => {
+                p::SideBySideChangeType::Added
+            }
+            crate::cmd::diff::SideBySideChangeType::Removed => {
+                p::SideBySideChangeType::Removed
+            }
+            crate::cmd::diff::SideBySideChangeType::Modified => {
+                p::SideBySideChangeType::Modified
+            }
+            crate::cmd::diff::SideBySideChangeType::Empty => {
+                p::SideBySideChangeType::Empty
+            }
+        }
+    }
+}
+
+impl From<crate::cmd::diff::SideBySideLine> for p::SideBySideLine {
+    fn from(l: crate::cmd::diff::SideBySideLine) -> Self {
+        let change_type_proto: p::SideBySideChangeType = l.change_type.into();
+        p::SideBySideLine {
+            left_line_no: l.left_line_no,
+            right_line_no: l.right_line_no,
+            left_content: l.left_content,
+            right_content: l.right_content,
+            change_type: change_type_proto as i32,
+        }
+    }
+}
+
+impl From<crate::cmd::diff::SideBySideFile> for p::SideBySideFile {
+    fn from(f: crate::cmd::diff::SideBySideFile) -> Self {
+        p::SideBySideFile {
+            path: f.path,
+            additions: f.additions as u64,
+            deletions: f.deletions as u64,
+            is_binary: f.is_binary,
+            is_rename: f.is_rename,
+            lines: f.lines.into_iter().map(Into::into).collect(),
+        }
+    }
+}
+
+impl From<crate::cmd::diff::SideBySideDiffResult> for p::SideBySideDiffResult {
+    fn from(r: crate::cmd::diff::SideBySideDiffResult) -> Self {
+        p::SideBySideDiffResult {
+            files: r.files.into_iter().map(Into::into).collect(),
+            total_additions: r.total_additions as u64,
+            total_deletions: r.total_deletions as u64,
+        }
+    }
+}
+
+impl From<crate::cmd::merge::MergeAnalysisResult> for p::MergeAnalysisResult {
+    fn from(r: crate::cmd::merge::MergeAnalysisResult) -> Self {
+        p::MergeAnalysisResult {
+            is_none: r.is_none,
+            is_normal: r.is_normal,
+            is_up_to_date: r.is_up_to_date,
+            is_fast_forward: r.is_fast_forward,
+            is_unborn: r.is_unborn,
+        }
+    }
+}
+
+impl From<crate::cmd::merge::MergePreferenceResult>
+    for p::MergePreferenceResult
+{
+    fn from(r: crate::cmd::merge::MergePreferenceResult) -> Self {
+        p::MergePreferenceResult {
+            is_none: r.is_none,
+            is_no_fast_forward: r.is_no_fast_forward,
+            is_fastforward_only: r.is_fastforward_only,
+        }
+    }
+}
+
+impl From<crate::cmd::merge::MergeOptions> for p::MergeOptions {
+    fn from(o: crate::cmd::merge::MergeOptions) -> Self {
+        p::MergeOptions {
+            find_renames: o.find_renames,
+            fail_on_conflict: o.fail_on_conflict,
+            skip_reuc: o.skip_reuc,
+            no_recursive: o.no_recursive,
+            rename_threshold: o.rename_threshold,
+            target_limit: o.target_limit,
+            recursion_limit: o.recursion_limit,
+        }
+    }
+}
+
+impl From<p::MergeOptions> for crate::cmd::merge::MergeOptions {
+    fn from(o: p::MergeOptions) -> Self {
+        crate::cmd::merge::MergeOptions {
+            find_renames: o.find_renames,
+            fail_on_conflict: o.fail_on_conflict,
+            skip_reuc: o.skip_reuc,
+            no_recursive: o.no_recursive,
+            rename_threshold: o.rename_threshold,
+            target_limit: o.target_limit,
+            recursion_limit: o.recursion_limit,
+        }
+    }
+}
+
+impl From<p::MergeCommitParams> for crate::cmd::merge::MergeCommitParams {
+    fn from(p: p::MergeCommitParams) -> Self {
+        crate::cmd::merge::MergeCommitParams {
+            their_commit: p.their_commit.unwrap_or_default().into(),
+            author: p.author.unwrap_or_default().into(),
+            committer: p.committer.unwrap_or_default().into(),
+            message: p.message,
+            update_ref: p.update_ref,
+            options: p.options.map(Into::into),
+        }
+    }
+}
+
+impl From<crate::cmd::merge::MergeTreeResult> for p::MergeTreeResult {
+    fn from(r: crate::cmd::merge::MergeTreeResult) -> Self {
+        p::MergeTreeResult {
+            tree_id: Some(r.tree_id.into()),
+            has_conflicts: r.has_conflicts,
+        }
+    }
+}
+
+impl From<p::SquashCommitParams> for crate::cmd::merge::SquashCommitParams {
+    fn from(p: p::SquashCommitParams) -> Self {
+        crate::cmd::merge::SquashCommitParams {
+            their_commit: p.their_commit.unwrap_or_default().into(),
+            options: p.options.map(Into::into),
+        }
+    }
+}
+
+impl From<crate::cmd::tag::TagItem> for p::TagItem {
+    fn from(t: crate::cmd::tag::TagItem) -> Self {
+        p::TagItem {
+            name: t.name,
+            oid: Some(t.oid.into()),
+            target: Some(t.target.into()),
+            is_annotated: t.is_annotated,
+            message: t.message,
+            tagger: t.tagger,
+            tagger_email: t.tagger_email,
+        }
+    }
+}
+
+impl From<crate::cmd::tag::TagSummary> for p::TagSummary {
+    fn from(s: crate::cmd::tag::TagSummary) -> Self {
+        p::TagSummary {
+            total_count: s.total_count as u64,
+        }
+    }
+}
+
+impl From<p::TagInitParams> for crate::cmd::tag::TagInitParams {
+    fn from(p: p::TagInitParams) -> Self {
+        crate::cmd::tag::TagInitParams {
+            name: p.name,
+            target: p.target.unwrap_or_default().into(),
+            message: p.message,
+            tagger: p.tagger.map(Into::into),
+            force: p.force,
+        }
+    }
+}
+
+impl From<p::TagDeleteParams> for crate::cmd::tag::TagDeleteParams {
+    fn from(p: p::TagDeleteParams) -> Self {
+        crate::cmd::tag::TagDeleteParams { name: p.name }
+    }
+}
+
+impl From<p::TagRenameParams> for crate::cmd::tag::TagRenameParams {
+    fn from(p: p::TagRenameParams) -> Self {
+        crate::cmd::tag::TagRenameParams {
+            old_name: p.old_name,
+            new_name: p.new_name,
+            force: p.force,
+        }
+    }
+}
+
+impl From<p::TagUpdateMessageParams>
+    for crate::cmd::tag::TagUpdateMessageParams
+{
+    fn from(p: p::TagUpdateMessageParams) -> Self {
+        crate::cmd::tag::TagUpdateMessageParams {
+            name: p.name,
+            message: p.message,
+            tagger: p.tagger.unwrap_or_default().into(),
+            force: p.force,
+        }
+    }
+}
+
+impl From<crate::cmd::tree::TreeKind> for p::TreeKind {
+    fn from(k: crate::cmd::tree::TreeKind) -> Self {
+        match k {
+            crate::cmd::tree::TreeKind::Blob => p::TreeKind::Blob,
+            crate::cmd::tree::TreeKind::Tree => p::TreeKind::Tree,
+            crate::cmd::tree::TreeKind::LfsPointer => p::TreeKind::LfsPointer,
+        }
+    }
+}
+
+impl From<crate::cmd::tree::TreeInfo> for p::TreeInfo {
+    fn from(i: crate::cmd::tree::TreeInfo) -> Self {
+        p::TreeInfo {
+            oid: Some(i.oid.into()),
+            entry_count: i.entry_count as u64,
+            is_empty: i.is_empty,
+        }
+    }
+}
+
+impl From<crate::cmd::tree::TreeEntry> for p::TreeEntry {
+    fn from(e: crate::cmd::tree::TreeEntry) -> Self {
+        let kind_proto: p::TreeKind = e.kind.into();
+        p::TreeEntry {
+            name: e.name,
+            oid: Some(e.oid.into()),
+            kind: kind_proto as i32,
+            filemode: e.filemode,
+            is_binary: e.is_binary,
+            is_lfs: e.is_lfs,
+            last_commit_message: String::new(),
+            last_commit_time: String::new(),
+            last_commit_author_name: String::new(),
+            last_commit_author_email: String::new(),
+        }
+    }
+}
+
+impl From<crate::cmd::blame::CommitBlameHunk> for p::CommitBlameHunk {
+    fn from(h: crate::cmd::blame::CommitBlameHunk) -> Self {
+        p::CommitBlameHunk {
+            commit_oid: Some(h.commit_oid.into()),
+            final_start_line: h.final_start_line,
+            final_lines: h.final_lines,
+            orig_start_line: h.orig_start_line,
+            orig_lines: h.orig_lines,
+            boundary: h.boundary,
+            orig_path: h.orig_path,
+        }
+    }
+}
+
+impl From<crate::cmd::blame::CommitBlameLine> for p::CommitBlameLine {
+    fn from(l: crate::cmd::blame::CommitBlameLine) -> Self {
+        p::CommitBlameLine {
+            commit_oid: Some(l.commit_oid.into()),
+            line_no: l.line_no,
+            content: l.content,
+            orig_path: l.orig_path,
+        }
+    }
+}
+
+impl From<p::BlameOptions> for crate::cmd::blame::BlameOptions {
+    fn from(o: p::BlameOptions) -> Self {
+        crate::cmd::blame::BlameOptions {
+            min_line: o.min_line.map(|l| l as usize),
+            max_line: o.max_line.map(|l| l as usize),
+            track_copies_same_file: o.track_copies_same_file,
+            track_copies_same_commit_moves: o.track_copies_same_commit_moves,
+            ignore_whitespace: o.ignore_whitespace,
+        }
+    }
+}
+
+impl From<p::ArchiveOptions> for crate::cmd::archive::ArchiveOptions {
+    fn from(o: p::ArchiveOptions) -> Self {
+        crate::cmd::archive::ArchiveOptions {
+            tree: o.tree.unwrap_or_default().into(),
+            prefix: o.prefix,
+            pathspec: o.pathspec,
+        }
+    }
+}
+
+impl From<p::BlobLoadParams> for crate::cmd::blob::BlobLoadParams {
+    fn from(p: p::BlobLoadParams) -> Self {
+        crate::cmd::blob::BlobLoadParams {
+            id: p.id.unwrap_or_default().into(),
+            path: p.path,
+        }
+    }
+}
+
+impl From<p::BlobSizeParams> for crate::cmd::blob::BlobSizeParams {
+    fn from(p: p::BlobSizeParams) -> Self {
+        crate::cmd::blob::BlobSizeParams {
+            id: p.id.unwrap_or_default().into(),
+            path: p.path,
+        }
+    }
+}
+
+impl From<p::BlobUploadParams> for crate::cmd::blob::BlobUploadParams {
+    fn from(p: p::BlobUploadParams) -> Self {
+        crate::cmd::blob::BlobUploadParams {
+            blob: p.blob,
+            path: p.path,
+        }
+    }
+}
+
+impl From<p::BlobChunkParam> for crate::cmd::blob::BlobChunkParam {
+    fn from(p: p::BlobChunkParam) -> Self {
+        crate::cmd::blob::BlobChunkParam {
+            path: p.path,
+            oid: p.oid.unwrap_or_default().into(),
+            size: p.size as usize,
+            offset: p.offset as usize,
+        }
+    }
+}
+
+impl From<crate::cmd::blob::BlobChunk> for p::BlobChunk {
+    fn from(c: crate::cmd::blob::BlobChunk) -> Self {
+        p::BlobChunk {
+            param: Some(c.param.into()),
+            chunk: c.chunk,
+        }
+    }
+}
+
+impl From<p::InitRepoParams> for crate::cmd::init::InitRepositoriesParams {
+    fn from(p: p::InitRepoParams) -> Self {
+        crate::cmd::init::InitRepositoriesParams {
+            namespace: p.namespace,
+            repo_name: p.repo_name,
+            default_branch: p.default_branch,
+            description: p.description,
+            initialize_with_readme: p.initialize_with_readme,
+            enable_lfs: p.enable_lfs,
+        }
+    }
+}
+
+impl From<crate::cmd::blob::BlobChunkParam> for p::BlobChunkParam {
+    fn from(p: crate::cmd::blob::BlobChunkParam) -> Self {
+        p::BlobChunkParam {
+            path: p.path,
+            oid: Some(p.oid.into()),
+            size: p.size as u64,
+            offset: p.offset as u64,
+        }
+    }
+}
diff --git a/lib/git/rpc/diff.rs b/lib/git/rpc/diff.rs
new file mode 100644
index 0000000..9141b3b
--- /dev/null
+++ b/lib/git/rpc/diff.rs
@@ -0,0 +1,180 @@
+use std::sync::Arc;
+
+use cache::AppCache;
+use tokio_stream::wrappers::ReceiverStream;
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct DiffServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+    pub cache: AppCache,
+}
+
+type DiffStream = ReceiverStream<Result<p::DiffDelta, Status>>;
+
+#[tonic::async_trait]
+impl p::diff_service_server::DiffService for DiffServiceImpl {
+    async fn diff_stats(
+        &self,
+        req: Request<p::DiffStatsRequest>,
+    ) -> Result<Response<p::DiffStatsResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let old_str = inner.old_oid.clone().map(|o| o.value).unwrap_or_default();
+        let new_str = inner.new_oid.clone().map(|o| o.value).unwrap_or_default();
+        let cache_key = format!("git:rpc:cache:diff:stats:{}:{}:{}", repo_id, old_str, new_str);
+
+        if let Ok(Some(cached)) = self.cache.get::<p::DiffStatsResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let old: crate::cmd::oid::ObjectId =
+            inner.old_oid.unwrap_or_default().into();
+        let new: crate::cmd::oid::ObjectId =
+            inner.new_oid.unwrap_or_default().into();
+        let opts = inner.options.map(Into::into);
+        let stats = tokio::task::spawn_blocking(move || {
+            bare.diff_stats(old, new, opts)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        let result = crate::cmd::diff::DiffResult { stats, deltas: vec![] };
+        let resp = p::DiffStatsResponse { result: Some(result.into()) };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    async fn diff_patch(
+        &self,
+        req: Request<p::DiffPatchRequest>,
+    ) -> Result<Response<p::DiffPatchResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let old_str = inner.old_oid.clone().map(|o| o.value).unwrap_or_default();
+        let new_str = inner.new_oid.clone().map(|o| o.value).unwrap_or_default();
+        let cache_key = format!("git:rpc:cache:diff:patch:{}:{}:{}", repo_id, old_str, new_str);
+
+        if let Ok(Some(cached)) = self.cache.get::<p::DiffPatchResponse>(&cache_key).await {
+            return Ok(Response::new(cached));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let old: crate::cmd::oid::ObjectId =
+            inner.old_oid.unwrap_or_default().into();
+        let new: crate::cmd::oid::ObjectId =
+            inner.new_oid.unwrap_or_default().into();
+        let opts = inner.options.map(Into::into);
+        let result = tokio::task::spawn_blocking(move || {
+            bare.diff_patch(old, new, opts)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        let resp = p::DiffPatchResponse { result: Some(result.into()) };
+        let _ = self.cache.set(&cache_key, &resp).await;
+        Ok(Response::new(resp))
+    }
+
+    type DiffStreamStream = DiffStream;
+
+    async fn diff_stream(
+        &self,
+        req: Request<p::DiffPatchRequest>,
+    ) -> Result<Response<DiffStream>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let old: crate::cmd::oid::ObjectId =
+            inner.old_oid.unwrap_or_default().into();
+        let new: crate::cmd::oid::ObjectId =
+            inner.new_oid.unwrap_or_default().into();
+        let opts = inner.options.map(Into::into);
+        let (tx, rx) = tokio::sync::mpsc::channel(128);
+        tokio::task::spawn_blocking(move || {
+            let result = bare.diff_patch(old, new, opts);
+            match result {
+                Ok(diff_result) => {
+                    for delta in diff_result.deltas {
+                        if tx.blocking_send(Ok(delta.into())).is_err() {
+                            break;
+                        }
+                    }
+                }
+                Err(e) => {
+                    let _ = tx.blocking_send(Err(to_status(e)));
+                }
+            }
+        });
+        Ok(Response::new(ReceiverStream::new(rx)))
+    }
+
+    async fn diff_patch_side_by_side(
+        &self,
+        req: Request<p::DiffPatchSideBySideRequest>,
+    ) -> Result<Response<p::DiffPatchSideBySideResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let old: crate::cmd::oid::ObjectId =
+            inner.old_oid.unwrap_or_default().into();
+        let new: crate::cmd::oid::ObjectId =
+            inner.new_oid.unwrap_or_default().into();
+        let opts = inner.options.map(Into::into);
+        let result = tokio::task::spawn_blocking(move || {
+            bare.diff_patch_side_by_side(old, new, opts)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::DiffPatchSideBySideResponse {
+            result: Some(result.into()),
+        }))
+    }
+
+    async fn diff_tree_to_tree(
+        &self,
+        req: Request<p::DiffTreeToTreeRequest>,
+    ) -> Result<Response<p::DiffTreeToTreeResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let old_tree: crate::cmd::oid::ObjectId =
+            inner.old_tree.unwrap_or_default().into();
+        let new_tree: crate::cmd::oid::ObjectId =
+            inner.new_tree.unwrap_or_default().into();
+        let options = inner.options.map(Into::into);
+        let result = tokio::task::spawn_blocking(move || {
+            bare.diff_tree_to_tree(old_tree, new_tree, options)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::DiffTreeToTreeResponse {
+            result: Some(result.into()),
+        }))
+    }
+
+    async fn diff_index_to_tree(
+        &self,
+        req: Request<p::DiffIndexToTreeRequest>,
+    ) -> Result<Response<p::DiffIndexToTreeResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let tree_oid: crate::cmd::oid::ObjectId =
+            inner.tree_oid.unwrap_or_default().into();
+        let options = inner.options.map(Into::into);
+        let result = tokio::task::spawn_blocking(move || {
+            bare.diff_index_to_tree(tree_oid, options)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::DiffIndexToTreeResponse {
+            result: Some(result.into()),
+        }))
+    }
+}
diff --git a/lib/git/rpc/error.rs b/lib/git/rpc/error.rs
new file mode 100644
index 0000000..5e90a26
--- /dev/null
+++ b/lib/git/rpc/error.rs
@@ -0,0 +1,48 @@
+use tonic::Status;
+
+use crate::errors::GitError;
+
+pub fn to_status(err: GitError) -> Status {
+    match err {
+        GitError::NotBareRepository => {
+            Status::not_found("not a bare repository")
+        }
+        GitError::CommandFailed {
+            status_code,
+            stderr,
+        } => {
+            let msg = format!(
+                "git command failed (status={status_code:?}): {stderr}"
+            );
+            Status::internal(msg)
+        }
+        GitError::UnsafeCommand(cmd) => {
+            Status::invalid_argument(format!("unsafe command: {cmd}"))
+        }
+        GitError::ObjectNotFound(oid) => {
+            Status::not_found(format!("object not found: {oid}"))
+        }
+        GitError::RefNotFound(ref_name) => {
+            Status::not_found(format!("ref not found: {ref_name}"))
+        }
+        GitError::ParseError(msg) => {
+            Status::internal(format!("parse error: {msg}"))
+        }
+        GitError::Io(e) => Status::internal(format!("io error: {e}")),
+        GitError::DatabaseError(e) => {
+            Status::internal(format!("database error{e}"))
+        }
+        GitError::RepoNotFound => Status::not_found("repo not found"),
+        GitError::Internal(msg) => Status::internal(msg),
+        GitError::NotFound(msg) => Status::not_found(msg),
+        GitError::InvalidOid(msg) => Status::invalid_argument(msg),
+        GitError::Locked(msg) => Status::failed_precondition(msg),
+        GitError::PermissionDenied(msg) => Status::permission_denied(msg),
+        GitError::AuthFailed(msg) => Status::unauthenticated(msg),
+        GitError::Gix(msg) => Status::internal(format!("gix error: {msg}")),
+    }
+}
+
+pub fn spawn_blocking_error(e: tokio::task::JoinError) -> Status {
+    Status::internal(format!("spawn_blocking failed: {e}"))
+}
diff --git a/lib/git/rpc/fork.rs b/lib/git/rpc/fork.rs
new file mode 100644
index 0000000..d7e807f
--- /dev/null
+++ b/lib/git/rpc/fork.rs
@@ -0,0 +1,44 @@
+use std::sync::Arc;
+
+use tonic::{Request, Response, Status};
+
+use crate::{
+    cmd::fork::ForkRepoParams,
+    rpc::{error::to_status, proto as p, registry::RepoRegistry},
+};
+
+pub struct ForkServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+}
+
+#[tonic::async_trait]
+impl p::fork_service_server::ForkService for ForkServiceImpl {
+    async fn fork_bare(
+        &self,
+        req: Request<p::ForkBareRequest>,
+    ) -> Result<Response<p::ForkBareResponse>, Status> {
+        let inner = req.into_inner();
+        let proto_params = inner.params.unwrap_or_default();
+
+        let params = ForkRepoParams {
+            namespace: proto_params.namespace,
+            repo_name: proto_params.repo_name,
+            default_branch: proto_params.default_branch,
+            description: proto_params.description,
+            enable_lfs: proto_params.enable_lfs,
+        };
+
+        let storage_root = inner.storage_root;
+        let source_storage_path = inner.source_storage_path;
+
+        let storage_path = ForkRepoParams::fork_bare(
+            storage_root,
+            source_storage_path,
+            params,
+        )
+        .await
+        .map_err(to_status)?;
+
+        Ok(Response::new(p::ForkBareResponse { storage_path }))
+    }
+}
diff --git a/lib/git/rpc/init.rs b/lib/git/rpc/init.rs
new file mode 100644
index 0000000..ac8b7a0
--- /dev/null
+++ b/lib/git/rpc/init.rs
@@ -0,0 +1,83 @@
+use std::sync::Arc;
+
+use tonic::{Request, Response, Status};
+
+use crate::{
+    cmd::init::InitRepositoriesParams,
+    rpc::{
+        error::{spawn_blocking_error, to_status},
+        proto as p,
+        registry::RepoRegistry,
+    },
+    sync::ReceiveSyncService,
+};
+
+pub struct InitServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+    pub sync: ReceiveSyncService,
+}
+
+#[tonic::async_trait]
+impl p::init_service_server::InitService for InitServiceImpl {
+    async fn init_bare(
+        &self,
+        req: Request<p::InitBareRequest>,
+    ) -> Result<Response<p::InitBareResponse>, Status> {
+        let inner = req.into_inner();
+        let proto_params = inner.params.unwrap_or_default();
+        let namespace = proto_params.namespace.clone();
+        let repo_name = proto_params.repo_name.clone();
+
+        let params = InitRepositoriesParams {
+            namespace,
+            repo_name: repo_name.clone(),
+            default_branch: proto_params.default_branch,
+            description: proto_params.description,
+            initialize_with_readme: proto_params.initialize_with_readme,
+            enable_lfs: proto_params.enable_lfs,
+        };
+
+        let storage_root = inner.storage_root;
+        let storage_path =
+            InitRepositoriesParams::init_bare(storage_root, params)
+                .await
+                .map_err(to_status)?;
+
+        // Note: init_bare creates a new repo; sync is triggered by the caller (service layer)
+        // because the repo UUID is assigned in the DB, not here.
+
+        Ok(Response::new(p::InitBareResponse { storage_path }))
+    }
+
+    async fn set_default_branch(
+        &self,
+        req: Request<p::SetDefaultBranchRequest>,
+    ) -> Result<Response<p::SetDefaultBranchResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let branch_name = inner.branch_name;
+        tokio::task::spawn_blocking(move || bare.set_default_branch(&branch_name))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::SetDefaultBranchResponse {}))
+    }
+
+    async fn clone_bare(
+        &self,
+        req: Request<p::CloneBareRequest>,
+    ) -> Result<Response<p::CloneBareResponse>, Status> {
+        let inner = req.into_inner();
+        let params = crate::cmd::init::CloneRepoParams {
+            namespace: inner.namespace,
+            repo_name: inner.repo_name,
+            source_url: inner.source_url,
+        };
+        let storage_root = inner.storage_root;
+        let storage_path =
+            crate::cmd::init::CloneRepoParams::clone_bare(storage_root, params)
+                .await
+                .map_err(to_status)?;
+        Ok(Response::new(p::CloneBareResponse { storage_path }))
+    }
+}
diff --git a/lib/git/rpc/merge.rs b/lib/git/rpc/merge.rs
new file mode 100644
index 0000000..d444f53
--- /dev/null
+++ b/lib/git/rpc/merge.rs
@@ -0,0 +1,208 @@
+use std::sync::Arc;
+
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct MergeServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+}
+
+#[tonic::async_trait]
+impl p::merge_service_server::MergeService for MergeServiceImpl {
+    async fn merge_base(
+        &self,
+        req: Request<p::MergeBaseRequest>,
+    ) -> Result<Response<p::MergeBaseResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let a: crate::cmd::oid::ObjectId =
+            inner.oid_a.unwrap_or_default().into();
+        let b: crate::cmd::oid::ObjectId =
+            inner.oid_b.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || bare.merge_base(a, b))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::MergeBaseResponse {
+            base_oid: Some(result.into()),
+        }))
+    }
+
+    async fn merge_base_many(
+        &self,
+        req: Request<p::MergeBaseManyRequest>,
+    ) -> Result<Response<p::MergeBaseManyResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let oids = inner.oids.into_iter().map(Into::into).collect::<Vec<_>>();
+        let result =
+            tokio::task::spawn_blocking(move || bare.merge_base_many(oids))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::MergeBaseManyResponse {
+            base_oid: Some(result.into()),
+        }))
+    }
+
+    async fn merge_base_octopus(
+        &self,
+        req: Request<p::MergeBaseOctopusRequest>,
+    ) -> Result<Response<p::MergeBaseOctopusResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let oids = inner.oids.into_iter().map(Into::into).collect::<Vec<_>>();
+        let result =
+            tokio::task::spawn_blocking(move || bare.merge_base_octopus(oids))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::MergeBaseOctopusResponse {
+            base_oid: Some(result.into()),
+        }))
+    }
+
+    async fn merge_analysis(
+        &self,
+        req: Request<p::MergeAnalysisRequest>,
+    ) -> Result<Response<p::MergeAnalysisResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let their_commit: crate::cmd::oid::ObjectId =
+            inner.oid_a.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.merge_analysis(their_commit)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::MergeAnalysisResponse {
+            analysis: Some(result.0.into()),
+            preference: Some(result.1.into()),
+        }))
+    }
+
+    async fn merge_analysis_for_ref(
+        &self,
+        req: Request<p::MergeAnalysisForRefRequest>,
+    ) -> Result<Response<p::MergeAnalysisForRefResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let ref_name = inner.ref_name.clone();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.merge_analysis_for_ref(ref_name)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::MergeAnalysisForRefResponse {
+            analysis: Some(result.0.into()),
+            preference: Some(result.1.into()),
+        }))
+    }
+
+    async fn merge_is_conflicted(
+        &self,
+        req: Request<p::MergeIsConflictedRequest>,
+    ) -> Result<Response<p::MergeIsConflictedResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result =
+            tokio::task::spawn_blocking(move || bare.merge_is_conflicted())
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::MergeIsConflictedResponse {
+            is_conflicted: result,
+        }))
+    }
+
+    async fn mergehead_list(
+        &self,
+        req: Request<p::MergeheadListRequest>,
+    ) -> Result<Response<p::MergeheadListResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result = tokio::task::spawn_blocking(move || bare.mergehead_list())
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::MergeheadListResponse {
+            oids: result.into_iter().map(Into::into).collect(),
+        }))
+    }
+
+    async fn merge_tree(
+        &self,
+        req: Request<p::MergeTreeRequest>,
+    ) -> Result<Response<p::MergeTreeResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let ours: crate::cmd::oid::ObjectId =
+            inner.ours.unwrap_or_default().into();
+        let theirs: crate::cmd::oid::ObjectId =
+            inner.theirs.unwrap_or_default().into();
+        let options = inner.options.map(Into::into);
+        let result = tokio::task::spawn_blocking(move || {
+            bare.merge_tree(ours, theirs, options)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::MergeTreeResponse {
+            result: Some(result.into()),
+        }))
+    }
+
+    async fn merge_commit(
+        &self,
+        req: Request<p::MergeCommitRequest>,
+    ) -> Result<Response<p::MergeCommitResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.merge_commit(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::MergeCommitResponse {
+            oid: Some(result.into()),
+        }))
+    }
+
+    async fn squash_commit(
+        &self,
+        req: Request<p::SquashCommitRequest>,
+    ) -> Result<Response<p::SquashCommitResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.squash_commit(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::SquashCommitResponse {
+            oid: Some(result.into()),
+        }))
+    }
+
+    async fn merge_abort(
+        &self,
+        req: Request<p::MergeAbortRequest>,
+    ) -> Result<Response<p::MergeAbortResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let _result = tokio::task::spawn_blocking(move || bare.merge_abort())
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::MergeAbortResponse {}))
+    }
+}
diff --git a/lib/git/rpc/mod.rs b/lib/git/rpc/mod.rs
new file mode 100644
index 0000000..5c18092
--- /dev/null
+++ b/lib/git/rpc/mod.rs
@@ -0,0 +1,19 @@
+pub mod archive;
+pub mod blame;
+pub mod blob;
+pub mod branch;
+pub mod commit;
+pub mod convert;
+pub mod diff;
+pub mod error;
+pub mod fork;
+pub mod init;
+pub mod merge;
+pub mod registry;
+pub mod server;
+pub mod tag;
+pub mod tree;
+
+pub mod proto {
+    tonic::include_proto!("git.v1");
+}
diff --git a/lib/git/rpc/registry.rs b/lib/git/rpc/registry.rs
new file mode 100644
index 0000000..fcfe0a2
--- /dev/null
+++ b/lib/git/rpc/registry.rs
@@ -0,0 +1,92 @@
+use std::{path::PathBuf, sync::Arc};
+
+use cache::AppCache;
+use dashmap::DashMap;
+use db::database::AppDatabase;
+use model::repos::RepoModel;
+use sqlx::query_as;
+use uuid::Uuid;
+
+use crate::bare::GitBare;
+
+const STORAGE_PATH_CACHE_KEY_PREFIX: &str = "git:rpc:repo:storage_path";
+
+#[derive(Clone)]
+pub struct RepoRegistry {
+    repos: DashMap<Uuid, GitBare>,
+    db: AppDatabase,
+    cache: AppCache,
+}
+
+impl RepoRegistry {
+    pub fn new(db: AppDatabase, cache: AppCache) -> Self {
+        Self {
+            repos: DashMap::new(),
+            db,
+            cache,
+        }
+    }
+
+    pub fn register(&self, repo_id: Uuid, bare_dir: PathBuf) {
+        let bare = GitBare { bare_dir };
+        self.repos.insert(repo_id, bare);
+    }
+
+    pub fn unregister(&self, repo_id: &Uuid) {
+        self.repos.remove(repo_id);
+    }
+
+    pub async fn get(
+        &self,
+        repo_id_str: &str,
+    ) -> Result<GitBare, tonic::Status> {
+        let repo_id = repo_id_str.parse::<Uuid>().map_err(|e| {
+            tonic::Status::invalid_argument(format!(
+                "invalid repo_id UUID: {e}"
+            ))
+        })?;
+
+        if let Some(bare) = self.repos.get(&repo_id) {
+            return Ok(bare.value().clone());
+        }
+
+        let storage_path = self.lookup_storage_path(repo_id).await?;
+        let bare = GitBare {
+            bare_dir: PathBuf::from(storage_path),
+        };
+        self.repos.insert(repo_id, bare.clone());
+        Ok(bare)
+    }
+
+    async fn lookup_storage_path(
+        &self,
+        repo_id: Uuid,
+    ) -> Result<String, tonic::Status> {
+        let cache_key = format!("{STORAGE_PATH_CACHE_KEY_PREFIX}:{repo_id}");
+
+        if let Ok(Some(path)) = self.cache.get::<String>(&cache_key).await {
+            return Ok(path);
+        }
+
+        let model: RepoModel = query_as(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at FROM repo WHERE id = $1 AND deleted_at IS NULL",
+        )
+            .bind(repo_id)
+            .fetch_one(self.db.reader())
+            .await
+            .map_err(|e| tonic::Status::internal(format!("database error: {e}")))?;
+
+        let path = model.storage_path;
+        let _ = self.cache.set(&cache_key, &path).await;
+
+        Ok(path)
+    }
+
+    pub fn list(&self) -> Vec<Uuid> {
+        self.repos.iter().map(|r| *r.key()).collect()
+    }
+}
+
+pub fn shared_registry(db: AppDatabase, cache: AppCache) -> Arc<RepoRegistry> {
+    Arc::new(RepoRegistry::new(db, cache))
+}
diff --git a/lib/git/rpc/server.rs b/lib/git/rpc/server.rs
new file mode 100644
index 0000000..3dcbeb9
--- /dev/null
+++ b/lib/git/rpc/server.rs
@@ -0,0 +1,156 @@
+use std::{net::SocketAddr, path::PathBuf, sync::Arc};
+
+use cache::AppCache;
+use db::database::AppDatabase;
+use tonic::transport::Server;
+use uuid::Uuid;
+
+use crate::sync::ReceiveSyncService;
+use crate::rpc::{
+    archive::ArchiveServiceImpl,
+    blame::BlameServiceImpl,
+    blob::BlobServiceImpl,
+    branch::BranchServiceImpl,
+    commit::CommitServiceImpl,
+    diff::DiffServiceImpl,
+    fork::ForkServiceImpl,
+    init::InitServiceImpl,
+    merge::MergeServiceImpl,
+    proto::{
+        archive_service_server::ArchiveServiceServer,
+        blame_service_server::BlameServiceServer,
+        blob_service_server::BlobServiceServer,
+        branch_service_server::BranchServiceServer,
+        commit_service_server::CommitServiceServer,
+        diff_service_server::DiffServiceServer,
+        fork_service_server::ForkServiceServer,
+        init_service_server::InitServiceServer,
+        merge_service_server::MergeServiceServer,
+        tag_service_server::TagServiceServer,
+        tree_service_server::TreeServiceServer,
+    },
+    registry::{RepoRegistry, shared_registry},
+    tag::TagServiceImpl,
+    tree::TreeServiceImpl,
+};
+
+type RepoId = Uuid;
+
+pub struct GitServer {
+    addr: SocketAddr,
+    pub registry: Arc<RepoRegistry>,
+    pub cache: AppCache,
+    pub sync: ReceiveSyncService,
+}
+
+impl GitServer {
+    pub fn new(addr: SocketAddr, db: AppDatabase, cache: AppCache, sync: ReceiveSyncService) -> Self {
+        Self {
+            addr,
+            cache: cache.clone(),
+            registry: shared_registry(db, cache),
+            sync,
+        }
+    }
+
+    pub fn register_repo(&self, repo_id: Uuid, bare_dir: PathBuf) {
+        self.registry.register(repo_id, bare_dir);
+    }
+
+    pub async fn serve(self) -> Result<(), Box<dyn std::error::Error>> {
+        let archive = ArchiveServiceServer::new(ArchiveServiceImpl {
+            registry: self.registry.clone(),
+        });
+        let blame = BlameServiceServer::new(BlameServiceImpl {
+            registry: self.registry.clone(),
+            cache: self.cache.clone(),
+        });
+        let blob = BlobServiceServer::new(BlobServiceImpl {
+            registry: self.registry.clone(),
+            cache: self.cache.clone(),
+        });
+        let branch = BranchServiceServer::new(BranchServiceImpl {
+            registry: self.registry.clone(),
+        });
+        let commit = CommitServiceServer::new(CommitServiceImpl {
+            registry: self.registry.clone(),
+            cache: self.cache.clone(),
+            sync: self.sync.clone(),
+        });
+        let diff = DiffServiceServer::new(DiffServiceImpl {
+            registry: self.registry.clone(),
+            cache: self.cache.clone(),
+        });
+        let fork = ForkServiceServer::new(ForkServiceImpl {
+            registry: self.registry.clone(),
+        });
+        let init = InitServiceServer::new(InitServiceImpl {
+            registry: self.registry.clone(),
+            sync: self.sync.clone(),
+        });
+        let merge = MergeServiceServer::new(MergeServiceImpl {
+            registry: self.registry.clone(),
+        });
+        let tag = TagServiceServer::new(TagServiceImpl {
+            registry: self.registry.clone(),
+        });
+        let tree = TreeServiceServer::new(TreeServiceImpl {
+            registry: self.registry.clone(),
+            cache: self.cache.clone(),
+        });
+
+        Server::builder()
+            .add_service(archive)
+            .add_service(blame)
+            .add_service(blob)
+            .add_service(branch)
+            .add_service(commit)
+            .add_service(diff)
+            .add_service(fork)
+            .add_service(init)
+            .add_service(merge)
+            .add_service(tag)
+            .add_service(tree)
+            .serve(self.addr)
+            .await?;
+
+        Ok(())
+    }
+}
+
+pub struct GitServerBuilder {
+    addr: SocketAddr,
+    db: AppDatabase,
+    cache: AppCache,
+    sync: ReceiveSyncService,
+    repos: Vec<(RepoId, PathBuf)>,
+}
+
+impl GitServerBuilder {
+    pub fn new(addr: SocketAddr, db: AppDatabase, cache: AppCache, sync: ReceiveSyncService) -> Self {
+        Self {
+            addr,
+            db,
+            cache,
+            sync,
+            repos: Vec::new(),
+        }
+    }
+
+    pub fn repo(
+        mut self,
+        repo_id: RepoId,
+        bare_dir: impl Into<PathBuf>,
+    ) -> Self {
+        self.repos.push((repo_id, bare_dir.into()));
+        self
+    }
+
+    pub fn build(self) -> GitServer {
+        let server = GitServer::new(self.addr, self.db, self.cache, self.sync);
+        for (repo_id, bare_dir) in self.repos {
+            server.register_repo(repo_id, bare_dir);
+        }
+        server
+    }
+}
diff --git a/lib/git/rpc/tag.rs b/lib/git/rpc/tag.rs
new file mode 100644
index 0000000..400aba3
--- /dev/null
+++ b/lib/git/rpc/tag.rs
@@ -0,0 +1,126 @@
+use std::sync::Arc;
+
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct TagServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+}
+
+#[tonic::async_trait]
+impl p::tag_service_server::TagService for TagServiceImpl {
+    async fn tag_list(
+        &self,
+        req: Request<p::TagListRequest>,
+    ) -> Result<Response<p::TagListResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result = tokio::task::spawn_blocking(move || bare.tag_list())
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::TagListResponse {
+            tags: result.into_iter().map(Into::into).collect(),
+        }))
+    }
+
+    async fn tag_info(
+        &self,
+        req: Request<p::TagInfoRequest>,
+    ) -> Result<Response<p::TagInfoResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let name = inner.name.clone();
+        let result = tokio::task::spawn_blocking(move || bare.tag_info(name))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::TagInfoResponse {
+            tag: Some(result.into()),
+        }))
+    }
+
+    async fn tag_summary(
+        &self,
+        req: Request<p::TagSummaryRequest>,
+    ) -> Result<Response<p::TagSummaryResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let result = tokio::task::spawn_blocking(move || bare.tag_summary())
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::TagSummaryResponse {
+            summary: Some(result.into()),
+        }))
+    }
+
+    async fn tag_init(
+        &self,
+        req: Request<p::TagInitRequest>,
+    ) -> Result<Response<p::TagInitResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || bare.tag_init(params))
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+        Ok(Response::new(p::TagInitResponse {
+            oid: Some(result.into()),
+        }))
+    }
+
+    async fn tag_delete(
+        &self,
+        req: Request<p::TagDeleteRequest>,
+    ) -> Result<Response<p::TagDeleteResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let _result =
+            tokio::task::spawn_blocking(move || bare.tag_delete(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::TagDeleteResponse {}))
+    }
+
+    async fn tag_rename(
+        &self,
+        req: Request<p::TagRenameRequest>,
+    ) -> Result<Response<p::TagRenameResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let _result =
+            tokio::task::spawn_blocking(move || bare.tag_rename(params))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::TagRenameResponse {}))
+    }
+
+    async fn tag_update_message(
+        &self,
+        req: Request<p::TagUpdateMessageRequest>,
+    ) -> Result<Response<p::TagUpdateMessageResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let params = inner.params.unwrap_or_default().into();
+        let result = tokio::task::spawn_blocking(move || {
+            bare.tag_update_message(params)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::TagUpdateMessageResponse {
+            oid: Some(result.into()),
+        }))
+    }
+}
diff --git a/lib/git/rpc/tree.rs b/lib/git/rpc/tree.rs
new file mode 100644
index 0000000..2ab875f
--- /dev/null
+++ b/lib/git/rpc/tree.rs
@@ -0,0 +1,167 @@
+use std::sync::Arc;
+
+use cache::AppCache;
+use tonic::{Request, Response, Status};
+
+use crate::rpc::{
+    error::{spawn_blocking_error, to_status},
+    proto as p,
+    registry::RepoRegistry,
+};
+
+pub struct TreeServiceImpl {
+    pub registry: Arc<RepoRegistry>,
+    pub cache: AppCache,
+}
+
+#[tonic::async_trait]
+impl p::tree_service_server::TreeService for TreeServiceImpl {
+    async fn tree_entries(
+        &self,
+        req: Request<p::TreeEntriesRequest>,
+    ) -> Result<Response<p::TreeEntriesResponse>, Status> {
+        let inner = req.into_inner();
+        let repo_id = inner.repo_id.clone();
+        let oid_val = inner.oid.clone().map(|o| o.value).unwrap_or_default();
+        let base_path = inner.base_path.clone();
+        let want_last = inner.last;
+        if !want_last {
+            let bare = self.registry.get(&repo_id).await?;
+            let oid = inner.oid.unwrap_or_default().into();
+            let entries = tokio::task::spawn_blocking(move || {
+                use crate::errors::GitError;
+                bare.tree_entries(oid)
+                    .map_err(|e| GitError::Internal(format!("tree_entries: {e}")))
+                    .map(|e| e.into_iter().map(Into::into).collect::<Vec<p::TreeEntry>>())
+            })
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+            return Ok(Response::new(p::TreeEntriesResponse { entries }));
+        }
+        let cache_key = format!(
+            "git:rpc:cache:tree:entries:{}:{}:{}",
+            repo_id, oid_val, base_path
+        );
+
+        if let Ok(Some(cached)) = self.cache.get::<Vec<p::TreeEntry>>(&cache_key).await {
+            return Ok(Response::new(p::TreeEntriesResponse { entries: cached }));
+        }
+
+        let bare = self.registry.get(&repo_id).await?;
+        let bare_bg = bare.clone();
+        let oid = inner.oid.unwrap_or_default().into();
+        let base_path_bg = base_path.clone();
+        let cache_bg = self.cache.clone();
+        let cache_key_bg = cache_key.clone();
+
+        let entries = tokio::task::spawn_blocking(move || {
+            use crate::errors::GitError;
+            bare.tree_entries(oid)
+                .map_err(|e| GitError::Internal(format!("tree_entries: {e}")))
+                .map(|e| e.into_iter().map(Into::into).collect::<Vec<p::TreeEntry>>())
+        })
+            .await
+            .map_err(spawn_blocking_error)?
+            .map_err(to_status)?;
+
+        let mut response = entries.clone();
+        for entry in &mut response {
+            entry.last_commit_message.clear();
+            entry.last_commit_time.clear();
+            entry.last_commit_author_name.clear();
+            entry.last_commit_author_email.clear();
+        }
+
+        tokio::task::spawn(async move {
+            let enriched = tokio::task::spawn_blocking(move || {
+                let paths: Vec<String> = entries.iter().map(|e| {
+                    if base_path_bg.is_empty() {
+                        e.name.clone()
+                    } else {
+                        format!("{}/{}", base_path_bg, e.name)
+                    }
+                }).collect();
+
+                let last_commits = match bare_bg.last_commits_for_paths(&paths) {
+                    Ok(lc) => lc,
+                    Err(_) => return entries,
+                };
+
+                let mut out = entries;
+                for (i, info) in last_commits.into_iter().enumerate() {
+                    if let Some(info) = info {
+                        if let Some(e) = out.get_mut(i) {
+                            e.last_commit_message = info.message;
+                            e.last_commit_time = info.time;
+                            e.last_commit_author_name = info.author_name;
+                            e.last_commit_author_email = info.author_email;
+                        }
+                    }
+                }
+                out
+            }).await;
+
+            if let Ok(entries) = enriched {
+                let _ = cache_bg.set(&cache_key_bg, &entries).await;
+            }
+        });
+
+        Ok(Response::new(p::TreeEntriesResponse { entries: response }))
+    }
+
+    async fn tree_entry_by_path(
+        &self,
+        req: Request<p::TreeEntryByPathRequest>,
+    ) -> Result<Response<p::TreeEntryByPathResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let tree_oid = inner.tree_oid.unwrap_or_default().into();
+        let path = inner.path;
+        let result = tokio::task::spawn_blocking(move || {
+            bare.tree_entry_by_path(tree_oid, path)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::TreeEntryByPathResponse {
+            entry: Some(result.into()),
+        }))
+    }
+
+    async fn tree_entry_by_path_from_commit(
+        &self,
+        req: Request<p::TreeEntryByPathFromCommitRequest>,
+    ) -> Result<Response<p::TreeEntryByPathFromCommitResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let commit_oid = inner.commit_oid.unwrap_or_default().into();
+        let path = inner.path;
+        let result = tokio::task::spawn_blocking(move || {
+            bare.tree_entry_by_path_from_commit(commit_oid, path)
+        })
+        .await
+        .map_err(spawn_blocking_error)?
+        .map_err(to_status)?;
+        Ok(Response::new(p::TreeEntryByPathFromCommitResponse {
+            entry: Some(result.into()),
+        }))
+    }
+
+    async fn resolve_tree(
+        &self,
+        req: Request<p::ResolveTreeRequest>,
+    ) -> Result<Response<p::ResolveTreeResponse>, Status> {
+        let inner = req.into_inner();
+        let bare = self.registry.get(&inner.repo_id).await?;
+        let oid = inner.oid.unwrap_or_default().into();
+        let result =
+            tokio::task::spawn_blocking(move || bare.resolve_tree(oid))
+                .await
+                .map_err(spawn_blocking_error)?
+                .map_err(to_status)?;
+        Ok(Response::new(p::ResolveTreeResponse {
+            info: Some(result.into()),
+        }))
+    }
+}
diff --git a/lib/git/ssh/authz.rs b/lib/git/ssh/authz.rs
new file mode 100644
index 0000000..1f9d680
--- /dev/null
+++ b/lib/git/ssh/authz.rs
@@ -0,0 +1,325 @@
+use base64::{Engine as _, engine::general_purpose};
+use db::{database::AppDatabase, sqlx};
+use model::{
+    repos::{RepoHistoryNameModel, RepoModel},
+    users::{UserModel, UserSshKeyModel},
+    workspace::{WkHistoryNameModel, WkMemberModel, WorkspaceModel},
+};
+use sha2::{Digest, Sha256};
+
+use crate::errors::GitError;
+
+pub struct SshAuthService {
+    db: AppDatabase,
+}
+
+pub struct SshKeyUser {
+    pub user: UserModel,
+    pub key_id: i64,
+    pub key_title: String,
+}
+
+impl SshAuthService {
+    pub fn new(db: AppDatabase) -> Self {
+        Self { db }
+    }
+
+    pub async fn find_repo(
+        &self,
+        namespace: &str,
+        repo_name: &str,
+    ) -> Result<RepoModel, GitError> {
+        let namespace = self.find_namespace(namespace).await?;
+        self.find_repository_by_name_and_wk(repo_name, namespace.id)
+            .await
+    }
+
+    async fn find_namespace(
+        &self,
+        namespace: &str,
+    ) -> Result<WorkspaceModel, GitError> {
+        let workspace = sqlx::query_as::<_, WorkspaceModel>(
+            "SELECT id, name, description, avatar_url, created_at FROM workspace WHERE name = $1",
+        )
+        .bind(namespace)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        if let Some(ws) = workspace {
+            return Ok(ws);
+        }
+
+        let history = sqlx::query_as::<_, WkHistoryNameModel>(
+            "SELECT id, wk, name, changed_by, created_at FROM wk_history_name WHERE name = $1",
+        )
+        .bind(namespace)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        if let Some(history) = history {
+            let ws = sqlx::query_as::<_, WorkspaceModel>(
+                "SELECT id, name, description, avatar_url, created_at FROM workspace WHERE id = $1",
+            )
+            .bind(history.wk)
+            .fetch_optional(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?;
+
+            if let Some(ws) = ws {
+                return Ok(ws);
+            }
+        }
+
+        Err(GitError::NotFound("Workspace not found".to_string()))
+    }
+
+    async fn find_repository_by_name_and_wk(
+        &self,
+        repo_name: &str,
+        wk_id: uuid::Uuid,
+    ) -> Result<RepoModel, GitError> {
+        let repo = sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at FROM repo WHERE name = $1 AND wk = $2",
+        )
+            .bind(repo_name)
+            .bind(wk_id)
+            .fetch_optional(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        if let Some(repo) = repo {
+            return Ok(repo);
+        }
+
+        let history = sqlx::query_as::<_, RepoHistoryNameModel>(
+            "SELECT id, repo, name, changed_by, created_at FROM repo_history_name WHERE name = $1",
+        )
+        .bind(repo_name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        if let Some(history) = history {
+            let repo = sqlx::query_as::<_, RepoModel>(
+                "SELECT id, wk, name, description, default_branch, visibility, size_bytes, is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at FROM repo WHERE id = $1 AND wk = $2",
+            )
+                .bind(history.repo)
+                .bind(wk_id)
+                .fetch_optional(self.db.reader())
+                .await
+                .map_err(|e| GitError::Internal(e.to_string()))?;
+
+            if let Some(repo) = repo {
+                return Ok(repo);
+            }
+        }
+
+        Err(GitError::NotFound("Repository not found".to_string()))
+    }
+
+    pub async fn find_user_by_public_key(
+        &self,
+        public_key_str: &str,
+    ) -> Result<Option<SshKeyUser>, sqlx::Error> {
+        let fingerprint =
+            match self.generate_fingerprint_from_public_key(public_key_str) {
+                Ok(fp) => fp,
+                Err(e) => {
+                    tracing::error!(
+                        "failed to generate SSH key fingerprint error={}",
+                        e
+                    );
+                    return Ok(None);
+                }
+            };
+
+        let fingerprint_preview = if fingerprint.len() > 16 {
+            format!("{}...", &fingerprint[..16])
+        } else {
+            fingerprint.clone()
+        };
+        tracing::info!(
+            "looking up user with SSH key fingerprint={}",
+            fingerprint_preview
+        );
+
+        let ssh_key = sqlx::query_as::<_, UserSshKeyModel>(
+            "SELECT id, \"user\", title, public_key, fingerprint, key_type, key_bits, is_verified, last_used_at, expires_at, is_revoked, created_at, updated_at FROM user_ssh_key WHERE fingerprint = $1 AND is_revoked = false",
+        )
+            .bind(&fingerprint)
+            .fetch_optional(self.db.reader())
+            .await?;
+
+        let ssh_key = match ssh_key {
+            Some(key) => key,
+            None => {
+                tracing::warn!("no SSH key found fingerprint={}", fingerprint);
+                return Ok(None);
+            }
+        };
+
+        if self.is_key_expired(&ssh_key) {
+            tracing::warn!(
+                "SSH key expired key_id={} expires_at={:?}",
+                ssh_key.id,
+                ssh_key.expires_at
+            );
+            return Ok(None);
+        }
+
+        let user_model = sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, last_sign_in_at, created_at, updated_at FROM \"user\" WHERE id = $1",
+        )
+            .bind(ssh_key.user)
+            .fetch_optional(self.db.reader())
+            .await?;
+
+        if let Some(user) = user_model {
+            tracing::info!(
+                "SSH key matched user={} key={}",
+                user.username,
+                ssh_key.title
+            );
+            return Ok(Some(SshKeyUser {
+                user,
+                key_id: ssh_key.id,
+                key_title: ssh_key.title,
+            }));
+        }
+
+        Ok(None)
+    }
+
+    fn is_key_expired(&self, ssh_key: &UserSshKeyModel) -> bool {
+        if let Some(expires_at) = ssh_key.expires_at {
+            let now = chrono::Utc::now();
+            now >= expires_at
+        } else {
+            false
+        }
+    }
+
+    pub fn update_key_last_used_async(&self, key_id: i64) {
+        let db_clone = self.db.clone();
+        tokio::spawn(async move {
+            if let Err(e) =
+                Self::update_key_last_used_sync(db_clone, key_id).await
+            {
+                tracing::warn!(
+                    "failed to update key last_used key_id={} error={}",
+                    key_id,
+                    e
+                );
+            }
+        });
+    }
+
+    async fn update_key_last_used_sync(
+        db: AppDatabase,
+        key_id: i64,
+    ) -> Result<(), sqlx::Error> {
+        let now = chrono::Utc::now();
+        sqlx::query("UPDATE user_ssh_key SET last_used_at = $1, updated_at = $2 WHERE id = $3")
+            .bind(now)
+            .bind(now)
+            .bind(key_id)
+            .execute(db.writer())
+            .await?;
+
+        tracing::info!("updated key last_used key_id={}", key_id);
+        Ok(())
+    }
+
+    pub async fn check_repo_permission(
+        &self,
+        user: &UserModel,
+        repo: &RepoModel,
+        is_write: bool,
+    ) -> bool {
+        if repo.created_by == user.id {
+            tracing::info!(
+                "user is repo owner user={} repo={}",
+                user.username,
+                repo.name
+            );
+            return true;
+        }
+
+        if !is_write && repo.visibility == "public" {
+            tracing::info!("public repo allows read access repo={}", repo.name);
+            return true;
+        }
+
+        let wk_id = repo.wk;
+        if self
+            .check_wk_member_permission(user, wk_id, is_write)
+            .await
+            .unwrap_or(false)
+        {
+            tracing::info!(
+                "user has workspace member access user={} repo={}",
+                user.username,
+                repo.name
+            );
+            return true;
+        }
+
+        tracing::warn!(
+            "access denied user={} repo={} is_write={}",
+            user.username,
+            repo.name,
+            is_write
+        );
+        false
+    }
+
+    async fn check_wk_member_permission(
+        &self,
+        user: &UserModel,
+        wk_id: uuid::Uuid,
+        is_write: bool,
+    ) -> Result<bool, sqlx::Error> {
+        let member = sqlx::query_as::<_, WkMemberModel>(
+            "SELECT wk, \"user\", owner, admin, join_at, leave_at FROM wk_member WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+        )
+            .bind(wk_id)
+            .bind(user.id)
+            .fetch_optional(self.db.reader())
+            .await?;
+
+        if let Some(member) = member {
+            if member.owner || member.admin {
+                return Ok(true);
+            }
+            Ok(!is_write)
+        } else {
+            Ok(false)
+        }
+    }
+
+    fn generate_fingerprint_from_public_key(
+        &self,
+        public_key_str: &str,
+    ) -> Result<String, String> {
+        let key_data_base64 = public_key_str
+            .split_whitespace()
+            .nth(1)
+            .ok_or("Invalid SSH key format")?;
+
+        let key_data = general_purpose::STANDARD
+            .decode(key_data_base64)
+            .map_err(|e| format!("Base64 decode error: {}", e))?;
+
+        let mut hasher = Sha256::new();
+        hasher.update(&key_data);
+        let hash = hasher.finalize();
+
+        let mut fingerprint = String::with_capacity(51);
+        fingerprint.push_str("SHA256:");
+        fingerprint.push_str(&general_purpose::STANDARD_NO_PAD.encode(&hash));
+
+        Ok(fingerprint)
+    }
+}
diff --git a/lib/git/ssh/branch_protect.rs b/lib/git/ssh/branch_protect.rs
new file mode 100644
index 0000000..abcfd4d
--- /dev/null
+++ b/lib/git/ssh/branch_protect.rs
@@ -0,0 +1,54 @@
+use model::repos::RepoProtectModel;
+
+use crate::ssh::ref_update::RefUpdate;
+
+fn ref_matches_protection(ref_name: &str, protection_pattern: &str) -> bool {
+    ref_name == protection_pattern
+        || ref_name.starts_with(&format!("{}/", protection_pattern))
+}
+
+pub fn check_branch_protection(
+    branch_protects: &[RepoProtectModel],
+    r#ref: &RefUpdate,
+) -> Option<String> {
+    for protection in branch_protects {
+        if !ref_matches_protection(&r#ref.name, &protection.pattern) {
+            continue;
+        }
+
+        if r#ref.new_oid == "0000000000000000000000000000000000000000" {
+            if !protection.allow_deletions {
+                return Some(format!(
+                    "protected branch rejected. Deletion of '{}' is forbidden. Create a PR or ask a maintainer to update branch protection.",
+                    r#ref.name
+                ));
+            }
+            continue;
+        }
+
+        if r#ref.name.starts_with("refs/tags/") {
+            continue;
+        }
+
+        let is_new_branch =
+            r#ref.old_oid == "0000000000000000000000000000000000000000";
+        if !is_new_branch
+            && r#ref.old_oid != r#ref.new_oid
+            && r#ref.name.starts_with("refs/heads/")
+            && !protection.allow_force_pushes
+        {
+            return Some(format!(
+                "protected branch rejected. Force push to '{}' is forbidden. Create a PR instead of rewriting protected history.",
+                r#ref.name
+            ));
+        }
+
+        if protection.require_pull_request {
+            return Some(format!(
+                "protected branch rejected. Direct push to '{}' is forbidden. Please push to a feature branch and create a PR.",
+                r#ref.name
+            ));
+        }
+    }
+    None
+}
diff --git a/lib/git/ssh/forward.rs b/lib/git/ssh/forward.rs
new file mode 100644
index 0000000..7a365d9
--- /dev/null
+++ b/lib/git/ssh/forward.rs
@@ -0,0 +1,51 @@
+use std::{future::Future, time::Duration};
+
+use actix_web::web::Bytes;
+use russh::{ChannelId, server::Handle};
+use tokio::{
+    io::{AsyncRead, AsyncReadExt},
+    time::sleep,
+};
+
+pub async fn forward<'a, R, Fut, Fwd>(
+    session_handle: &'a Handle,
+    chan_id: ChannelId,
+    r: &mut R,
+    mut fwd: Fwd,
+) -> Result<(), russh::Error>
+where
+    R: AsyncRead + Send + Unpin,
+    Fut: Future<Output = Result<(), Bytes>> + 'a,
+    Fwd: FnMut(&'a Handle, ChannelId, Bytes) -> Fut,
+{
+    const BUF_SIZE: usize = 1024 * 32;
+    const MAX_RETRIES: usize = 5;
+    const RETRY_DELAY: u64 = 10;
+
+    let mut buf = [0u8; BUF_SIZE];
+    loop {
+        let read = r.read(&mut buf).await.map_err(russh::Error::IO)?;
+
+        if read == 0 {
+            break;
+        }
+
+        let mut chunk = Bytes::copy_from_slice(&buf[..read]);
+        let mut retries = 0;
+        loop {
+            match fwd(session_handle, chan_id, chunk).await {
+                Ok(()) => break,
+                Err(unsent) => {
+                    retries += 1;
+                    if retries >= MAX_RETRIES {
+                        return Ok(());
+                    }
+                    chunk = unsent;
+                    sleep(Duration::from_millis(RETRY_DELAY)).await;
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
diff --git a/lib/git/ssh/git_service.rs b/lib/git/ssh/git_service.rs
new file mode 100644
index 0000000..3ed86af
--- /dev/null
+++ b/lib/git/ssh/git_service.rs
@@ -0,0 +1,92 @@
+use std::{path::PathBuf, str::FromStr};
+
+#[derive(Copy, Clone, PartialEq, Eq, Debug)]
+pub enum GitService {
+    UploadPack,
+    ReceivePack,
+    UploadArchive,
+}
+
+impl FromStr for GitService {
+    type Err = ();
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "upload-pack" => Ok(Self::UploadPack),
+            "receive-pack" => Ok(Self::ReceivePack),
+            "upload-archive" => Ok(Self::UploadArchive),
+            _ => Err(()),
+        }
+    }
+}
+
+pub fn parse_git_command(cmd: &str) -> Option<(GitService, &str)> {
+    let (svc, path) = match cmd.split_once(' ') {
+        Some(("git-receive-pack", path)) => (GitService::ReceivePack, path),
+        Some(("git-upload-pack", path)) => (GitService::UploadPack, path),
+        Some(("git-upload-archive", path)) => (GitService::UploadArchive, path),
+        _ => return None,
+    };
+    Some((svc, strip_apostrophes(path)))
+}
+
+pub fn parse_repo_path(path: &str) -> Option<(&str, &str)> {
+    let path = path.trim_matches('/');
+    let mut parts = path.splitn(2, '/');
+    match (parts.next(), parts.next()) {
+        (Some(owner), Some(repo)) if !owner.is_empty() && !repo.is_empty() => {
+            Some((owner, repo))
+        }
+        _ => None,
+    }
+}
+
+pub fn build_git_command(
+    service: GitService,
+    path: PathBuf,
+) -> tokio::process::Command {
+    let mut cmd = tokio::process::Command::new("git");
+
+    let cwd = match path.canonicalize() {
+        Ok(p) => p,
+        Err(e) => {
+            tracing::debug!(error = %e, "path canonicalize failed, falling back to raw path");
+            path.clone()
+        }
+    };
+    cmd.current_dir(cwd);
+
+    match service {
+        GitService::UploadPack => {
+            cmd.arg("upload-pack");
+        }
+        GitService::ReceivePack => {
+            cmd.arg("receive-pack");
+        }
+        GitService::UploadArchive => {
+            cmd.arg("upload-archive");
+        }
+    }
+
+    cmd.arg(".")
+        .env("GIT_CONFIG_NOSYSTEM", "1")
+        .env("GIT_NO_REPLACE_OBJECTS", "1");
+
+    #[cfg(unix)]
+    {
+        cmd.env("GIT_CONFIG_GLOBAL", "/dev/null")
+            .env("GIT_CONFIG_SYSTEM", "/dev/null");
+    }
+    #[cfg(windows)]
+    {
+        let nul = "NUL";
+        cmd.env("GIT_CONFIG_GLOBAL", nul)
+            .env("GIT_CONFIG_SYSTEM", nul);
+    }
+
+    cmd
+}
+
+fn strip_apostrophes(s: &str) -> &str {
+    s.trim_matches('\'')
+}
diff --git a/lib/git/ssh/handler.rs b/lib/git/ssh/handler.rs
new file mode 100644
index 0000000..b48312e
--- /dev/null
+++ b/lib/git/ssh/handler.rs
@@ -0,0 +1,1064 @@
+use std::{
+    collections::{HashMap, HashSet},
+    io,
+    net::SocketAddr,
+    path::PathBuf,
+    process::Stdio,
+    sync::Arc,
+    time::Duration,
+};
+
+use cache::AppCache;
+use db::{database::AppDatabase, sqlx};
+use model::{
+    repos::{RepoModel, RepoProtectModel},
+    users::UserModel,
+};
+use russh::{
+    Channel, ChannelId, Disconnect,
+    keys::{Certificate, PublicKey},
+    server::{Auth, Msg, Session},
+};
+use tokio::{
+    io::AsyncWriteExt,
+    process::ChildStdin,
+    sync::{Mutex, mpsc::Sender},
+    time::sleep,
+};
+
+use crate::{
+    ssh::{
+        SshTokenService,
+        authz::SshAuthService,
+        branch_protect::check_branch_protection,
+        forward::forward,
+        git_service::{
+            GitService, build_git_command, parse_git_command, parse_repo_path,
+        },
+        ref_update::RefUpdate,
+    },
+    sync::{
+        ReceiveSyncService, RepoReceiveSyncTask,
+        push_queue::{
+            PushQueueEvent, PushQueueWaitError, wait_for_push_queue_slot,
+        },
+    },
+};
+
+const PRE_PACK_LIMIT: usize = 1_048_576;
+const ZERO_OID: &str = "0000000000000000000000000000000000000000";
+
+pub struct SSHandle {
+    pub repo: Option<PathBuf>,
+    pub model: Option<RepoModel>,
+    pub stdin: HashMap<ChannelId, ChildStdin>,
+    pub eof: HashMap<ChannelId, Sender<bool>>,
+    pub operator: Option<UserModel>,
+    pub db: AppDatabase,
+    pub auth: SshAuthService,
+    pub buffer: HashMap<ChannelId, Vec<u8>>,
+    pub branch: HashMap<ChannelId, Vec<RefUpdate>>,
+    pub post_receive_refs: HashMap<ChannelId, Arc<Mutex<Vec<RefUpdate>>>>,
+    pub service: Option<GitService>,
+    pub cache: AppCache,
+    pub sync: ReceiveSyncService,
+    pub upload_pack_eof_sent: HashSet<ChannelId>,
+    pub token_service: SshTokenService,
+    pub client_addr: Option<SocketAddr>,
+}
+
+impl SSHandle {
+    pub fn new(
+        db: AppDatabase,
+        cache: AppCache,
+        sync: ReceiveSyncService,
+        token_service: SshTokenService,
+        client_addr: Option<SocketAddr>,
+    ) -> Self {
+        let auth = SshAuthService::new(db.clone());
+        let addr_str = client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+        tracing::info!("SSH handler created client={}", addr_str);
+        Self {
+            repo: None,
+            model: None,
+            stdin: HashMap::new(),
+            eof: HashMap::new(),
+            operator: None,
+            db,
+            auth,
+            buffer: HashMap::new(),
+            branch: HashMap::new(),
+            post_receive_refs: HashMap::new(),
+            service: None,
+            cache,
+            sync,
+            upload_pack_eof_sent: HashSet::new(),
+            token_service,
+            client_addr,
+        }
+    }
+
+    fn cleanup_channel(&mut self, channel_id: ChannelId) {
+        if let Some(stdin) = self.stdin.remove(&channel_id) {
+            let channel_id_for_task = channel_id;
+            tokio::spawn(async move {
+                let _ = tokio::time::timeout(Duration::from_secs(5), async {
+                    let mut stdin = stdin;
+                    if let Err(e) = stdin.flush().await {
+                        tracing::warn!(error = %e, "ssh_cleanup_flush_failed channel={:?}", channel_id_for_task);
+                    }
+                    let _ = stdin.shutdown().await;
+                })
+                .await;
+            });
+        }
+        self.eof.remove(&channel_id);
+        self.post_receive_refs.remove(&channel_id);
+        self.upload_pack_eof_sent.remove(&channel_id);
+    }
+
+    fn format_post_receive_hints(
+        namespace: &str,
+        repo: &RepoModel,
+        refs: &[RefUpdate],
+        queue: Option<(usize, usize)>,
+    ) -> String {
+        let mut lines = Vec::new();
+        for r#ref in refs {
+            if r#ref.old_oid == ZERO_OID
+                && r#ref.name.starts_with("refs/heads/")
+            {
+                let branch = r#ref.name.trim_start_matches("refs/heads/");
+                lines.push(format!(
+                    "remote: new branch '{}' pushed. Create a PR: /{}/repo/{}/pulls/new?head={}\r\n",
+                    branch,
+                    namespace,
+                    repo.name,
+                    branch
+                ));
+            }
+        }
+        if let Some((position, total)) = queue {
+            lines.push(format!(
+                "remote: repository sync queued ({}/{}). Metadata, webhooks and search indexes will update shortly.\r\n",
+                position, total
+            ));
+        }
+        lines.concat()
+    }
+}
+
+impl Drop for SSHandle {
+    fn drop(&mut self) {
+        let addr_str = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+        tracing::info!("ssh_handler_dropped client={}", addr_str);
+
+        let channel_ids: Vec<_> = self.stdin.keys().copied().collect();
+        for channel_id in channel_ids {
+            self.cleanup_channel(channel_id);
+        }
+    }
+}
+
+impl russh::server::Handler for SSHandle {
+    type Error = russh::Error;
+
+    async fn auth_none(&mut self, user: &str) -> Result<Auth, Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+        tracing::info!(
+            "auth_none_received user={} client={}",
+            user,
+            client_info
+        );
+        Ok(Auth::UnsupportedMethod)
+    }
+
+    async fn auth_password(
+        &mut self,
+        _user: &str,
+        token: &str,
+    ) -> Result<Auth, Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+
+        if token.is_empty() {
+            tracing::warn!("auth_rejected_empty_token client={}", client_info);
+            return Err(russh::Error::NotAuthenticated);
+        }
+
+        tracing::info!("auth_token_attempt client={}", client_info);
+
+        let user_model =
+            match self.token_service.find_user_by_token(token).await {
+                Ok(Some(model)) => model,
+                Ok(None) => {
+                    tracing::warn!(
+                        "auth_rejected_token_not_found client={}",
+                        client_info
+                    );
+                    return Err(russh::Error::NotAuthenticated);
+                }
+                Err(e) => {
+                    tracing::error!("auth_token_error error={}", e);
+                    return Err(russh::Error::NotAuthenticated);
+                }
+            };
+
+        tracing::info!(
+            "auth_token_success user={} client={}",
+            user_model.username,
+            client_info
+        );
+        self.operator = Some(user_model);
+        Ok(Auth::Accept)
+    }
+
+    async fn auth_publickey_offered(
+        &mut self,
+        user: &str,
+        public_key: &PublicKey,
+    ) -> Result<Auth, Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+
+        if user != "git" {
+            tracing::warn!(
+                "auth_publickey_offer_rejected_invalid_username user={} client={}",
+                user,
+                client_info
+            );
+            return Err(russh::Error::NotAuthenticated);
+        }
+
+        let public_key_str = public_key.to_string();
+        if public_key_str.len() < 32 {
+            tracing::warn!(
+                "auth_publickey_offer_rejected_invalid_key_length key_length={}",
+                public_key_str.len()
+            );
+            return Err(russh::Error::NotAuthenticated);
+        }
+
+        tracing::info!("auth_publickey_offer client={}", client_info);
+        match self.auth.find_user_by_public_key(&public_key_str).await {
+            Ok(Some(key_user)) => {
+                tracing::info!(
+                    "auth_publickey_offer_accepted user={} key={} client={}",
+                    key_user.user.username,
+                    key_user.key_title,
+                    client_info
+                );
+                Ok(Auth::Accept)
+            }
+            Ok(None) => {
+                tracing::warn!(
+                    "auth_publickey_offer_rejected_key_not_found client={}",
+                    client_info
+                );
+                Err(russh::Error::NotAuthenticated)
+            }
+            Err(e) => {
+                tracing::error!("auth_publickey_offer_error error={}", e);
+                Err(russh::Error::NotAuthenticated)
+            }
+        }
+    }
+
+    async fn auth_publickey(
+        &mut self,
+        user: &str,
+        public_key: &PublicKey,
+    ) -> Result<Auth, Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+
+        if user != "git" {
+            tracing::warn!(
+                "auth_rejected_invalid_username user={} client={}",
+                user,
+                client_info
+            );
+            return Err(russh::Error::NotAuthenticated);
+        }
+        let public_key_str = public_key.to_string();
+        if public_key_str.len() < 32 {
+            tracing::warn!(
+                "auth_rejected_invalid_key_length key_length={}",
+                public_key_str.len()
+            );
+            return Err(russh::Error::NotAuthenticated);
+        }
+
+        tracing::info!("auth_publickey_attempt client={}", client_info);
+        let key_user =
+            match self.auth.find_user_by_public_key(&public_key_str).await {
+                Ok(Some(key_user)) => key_user,
+                Ok(None) => {
+                    tracing::warn!(
+                        "auth_rejected_key_not_found client={}",
+                        client_info
+                    );
+                    return Err(russh::Error::NotAuthenticated);
+                }
+                Err(e) => {
+                    tracing::error!("auth_publickey_error error={}", e);
+                    return Err(russh::Error::NotAuthenticated);
+                }
+            };
+
+        tracing::info!(
+            "auth_publickey_success user={} client={}",
+            key_user.user.username,
+            client_info
+        );
+        self.auth.update_key_last_used_async(key_user.key_id);
+        self.operator = Some(key_user.user);
+        Ok(Auth::Accept)
+    }
+
+    async fn auth_openssh_certificate(
+        &mut self,
+        user: &str,
+        certificate: &Certificate,
+    ) -> Result<Auth, Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+
+        if user != "git" {
+            tracing::warn!(
+                "auth_rejected_invalid_username user={} client={}",
+                user,
+                client_info
+            );
+            return Err(russh::Error::NotAuthenticated);
+        }
+        let public_key_str = certificate.to_string();
+        if public_key_str.len() < 32 {
+            tracing::warn!(
+                "auth_rejected_invalid_key_length key_length={}",
+                public_key_str.len()
+            );
+            return Err(russh::Error::NotAuthenticated);
+        }
+
+        tracing::info!("auth_publickey_attempt client={}", client_info);
+        let key_user =
+            match self.auth.find_user_by_public_key(&public_key_str).await {
+                Ok(Some(key_user)) => key_user,
+                Ok(None) => {
+                    tracing::warn!(
+                        "auth_rejected_key_not_found client={}",
+                        client_info
+                    );
+                    return Err(russh::Error::NotAuthenticated);
+                }
+                Err(e) => {
+                    tracing::error!("auth_publickey_error error={}", e);
+                    return Err(russh::Error::NotAuthenticated);
+                }
+            };
+
+        tracing::info!(
+            "auth_publickey_success user={} client={}",
+            key_user.user.username,
+            client_info
+        );
+        self.auth.update_key_last_used_async(key_user.key_id);
+        self.operator = Some(key_user.user);
+        Ok(Auth::Accept)
+    }
+
+    async fn channel_close(
+        &mut self,
+        channel: ChannelId,
+        _: &mut Session,
+    ) -> Result<(), Self::Error> {
+        tracing::info!(
+            "channel_close channel={:?} client={:?}",
+            channel,
+            self.client_addr
+        );
+        self.cleanup_channel(channel);
+        Ok(())
+    }
+
+    async fn channel_eof(
+        &mut self,
+        channel: ChannelId,
+        _: &mut Session,
+    ) -> Result<(), Self::Error> {
+        tracing::info!(
+            "channel_eof channel={:?} client={:?}",
+            channel,
+            self.client_addr
+        );
+
+        if let Some(eof) = self.eof.get(&channel) {
+            let _ = eof.send(true).await;
+        }
+
+        if let Some(mut stdin) = self.stdin.remove(&channel) {
+            tracing::info!(
+                "Closing stdin channel={:?} client={:?}",
+                channel,
+                self.client_addr
+            );
+            let _ = tokio::time::timeout(Duration::from_secs(5), async {
+                if let Err(e) = stdin.flush().await {
+                    tracing::warn!(error = %e, "ssh_eof_flush_failed channel={:?}", channel);
+                }
+                let _ = stdin.shutdown().await;
+            })
+            .await;
+        }
+
+        Ok(())
+    }
+
+    async fn channel_open_session(
+        &mut self,
+        channel: Channel<Msg>,
+        session: &mut Session,
+    ) -> Result<bool, Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+        tracing::info!(
+            "channel_open_session channel={:?} client={}",
+            channel,
+            client_info
+        );
+        if let Err(e) = session.flush() {
+            tracing::warn!(error = %e, "ssh_session_flush_failed");
+        }
+        Ok(true)
+    }
+
+    async fn pty_request(
+        &mut self,
+        channel: ChannelId,
+        term: &str,
+        col_width: u32,
+        row_height: u32,
+        _pix_width: u32,
+        _pix_height: u32,
+        _modes: &[(russh::Pty, u32)],
+        session: &mut Session,
+    ) -> Result<(), Self::Error> {
+        tracing::warn!(
+            "pty_request not supported channel={:?} term={} cols={} rows={}",
+            channel,
+            term,
+            col_width,
+            row_height
+        );
+        if let Err(e) = session.flush() {
+            tracing::warn!(error = %e, "ssh_session_flush_failed");
+        }
+        Ok(())
+    }
+
+    async fn subsystem_request(
+        &mut self,
+        channel: ChannelId,
+        name: &str,
+        session: &mut Session,
+    ) -> Result<(), Self::Error> {
+        tracing::info!(
+            "subsystem_request channel={:?} subsystem={}",
+            channel,
+            name
+        );
+        if let Err(e) = session.flush() {
+            tracing::warn!(error = %e, "ssh_session_flush_failed");
+        }
+        Ok(())
+    }
+
+    async fn data(
+        &mut self,
+        channel: ChannelId,
+        data: &[u8],
+        session: &mut Session,
+    ) -> Result<(), Self::Error> {
+        if matches!(self.service, Some(GitService::ReceivePack)) {
+            if !self.branch.contains_key(&channel) {
+                let bf = self.buffer.entry(channel).or_default();
+
+                if bf.len() + data.len() > PRE_PACK_LIMIT {
+                    tracing::warn!(
+                        "ssh_pre_pack_too_large channel={:?}",
+                        channel
+                    );
+                    let msg = "remote: Ref negotiation exceeds size limit\r\n";
+                    let _ = session.extended_data(
+                        channel,
+                        1,
+                        msg.as_bytes().to_vec(),
+                    );
+                    let _ = session.exit_status_request(channel, 1);
+                    let _ = session.eof(channel);
+                    let _ = session.close(channel);
+                    self.cleanup_channel(channel);
+                    return Ok(());
+                }
+
+                bf.extend_from_slice(data);
+
+                if !bf.windows(4).any(|w| w == b"0000") {
+                    return Ok(());
+                }
+
+                let buffered = self.buffer.remove(&channel).unwrap_or_default();
+
+                match RefUpdate::parse_ref_updates(&buffered) {
+                    Ok(refs) => {
+                        if let Some(model) = &self.model {
+                            let branch_protect_roles = sqlx::query_as::<_, RepoProtectModel>(
+                                "SELECT id, repo, pattern, require_pull_request, required_approvals, require_status_checks, required_status_contexts, enforce_admins, allow_force_pushes, allow_deletions, created_at, updated_at FROM repo_protect WHERE repo = $1",
+                            )
+                                .bind(model.id)
+                                .fetch_all(self.db.reader())
+                                .await
+                                .map_err(|e| {
+                                    russh::Error::IO(io::Error::new(io::ErrorKind::Other, e))
+                                })?;
+
+                            for r#ref in &refs {
+                                if let Some(msg) = check_branch_protection(
+                                    &branch_protect_roles,
+                                    r#ref,
+                                ) {
+                                    let full_msg =
+                                        format!("remote: {}\r\n", msg);
+                                    let _ = session.extended_data(
+                                        channel,
+                                        1,
+                                        full_msg.into_bytes(),
+                                    );
+                                    let _ =
+                                        session.exit_status_request(channel, 1);
+                                    let _ = session.eof(channel);
+                                    let _ = session.close(channel);
+                                    self.cleanup_channel(channel);
+                                    return Ok(());
+                                }
+                            }
+                        }
+                        if let Some(refs_for_hints) =
+                            self.post_receive_refs.get(&channel)
+                        {
+                            *refs_for_hints.lock().await = refs.clone();
+                        }
+                        self.branch.insert(channel, refs);
+                    }
+                    Err(e) => {
+                        tracing::warn!("ref_update_parse_error error={:?}", e);
+                        if let Some(refs_for_hints) =
+                            self.post_receive_refs.get(&channel)
+                        {
+                            refs_for_hints.lock().await.clear();
+                        }
+                        self.branch.insert(channel, vec![]);
+                    }
+                }
+
+                if let Some(stdin) = self.stdin.get_mut(&channel) {
+                    stdin.write_all(&buffered).await?;
+                    stdin.flush().await?;
+                }
+                return Ok(());
+            }
+
+            if let Some(stdin) = self.stdin.get_mut(&channel) {
+                stdin.write_all(data).await?;
+                stdin.flush().await?;
+            }
+            return Ok(());
+        }
+
+        if let Some(stdin) = self.stdin.get_mut(&channel) {
+            stdin.write_all(data).await?;
+            if matches!(self.service, Some(GitService::UploadPack))
+                && !self.upload_pack_eof_sent.contains(&channel)
+            {
+                let has_flush_pkt = data.windows(4).any(|w| w == b"0000");
+                if has_flush_pkt {
+                    stdin.flush().await?;
+                    let _ = stdin.shutdown().await;
+                    self.upload_pack_eof_sent.insert(channel);
+                }
+            }
+        }
+        Ok(())
+    }
+
+    async fn shell_request(
+        &mut self,
+        channel_id: ChannelId,
+        session: &mut Session,
+    ) -> Result<(), Self::Error> {
+        if let Some(user) = &self.operator {
+            let welcome_msg = format!(
+                "Hi {}! You've successfully authenticated, but interactive shell access is not provided.\r\n",
+                user.username
+            );
+
+            tracing::info!("shell_request user={}", user.username);
+            let _ = session.data(channel_id, welcome_msg.into_bytes());
+            let _ = session.exit_status_request(channel_id, 0);
+            let _ = session.eof(channel_id);
+            let _ = session.close(channel_id);
+            let _ = session.flush();
+        } else {
+            tracing::warn!(
+                "shell_request_unauthenticated channel={:?}",
+                channel_id
+            );
+            let msg = "Authentication required\r\n";
+            let _ = session.data(channel_id, msg.as_bytes().to_vec());
+            let _ = session.exit_status_request(channel_id, 1);
+            let _ = session.eof(channel_id);
+            let _ = session.close(channel_id);
+            let _ = session.flush();
+        }
+        Ok(())
+    }
+
+    async fn exec_request(
+        &mut self,
+        channel_id: ChannelId,
+        data: &[u8],
+        session: &mut Session,
+    ) -> Result<(), Self::Error> {
+        let client_info = self
+            .client_addr
+            .map(|addr| format!("{}", addr))
+            .unwrap_or_else(|| "unknown".to_string());
+
+        tracing::info!(
+            "exec_request received channel={:?} client={}",
+            channel_id,
+            client_info
+        );
+
+        let git_shell_cmd = match std::str::from_utf8(data) {
+            Ok(cmd) => cmd.trim(),
+            Err(e) => {
+                tracing::error!("invalid_command_encoding error={}", e);
+                let _ = session.disconnect(
+                    Disconnect::ServiceNotAvailable,
+                    "Invalid command encoding",
+                    "",
+                );
+                return Err(russh::Error::Disconnect);
+            }
+        };
+        let (service, path) = match parse_git_command(git_shell_cmd) {
+            Some((s, p)) => (s, p),
+            None => {
+                tracing::error!(
+                    "invalid_git_command command={}",
+                    git_shell_cmd
+                );
+                let msg = format!("Invalid git command: {}", git_shell_cmd);
+                let _ = session.disconnect(
+                    Disconnect::ServiceNotAvailable,
+                    &msg,
+                    "",
+                );
+                return Err(russh::Error::Disconnect);
+            }
+        };
+        self.service = Some(service);
+        let (owner, repo) = match parse_repo_path(path) {
+            Some(pair) => pair,
+            None => {
+                let msg = format!("Invalid repository path: {}", path);
+                tracing::error!("invalid_repo_path path={}", path);
+                let _ = session.disconnect(
+                    Disconnect::ServiceNotAvailable,
+                    &msg,
+                    "",
+                );
+                return Err(russh::Error::Disconnect);
+            }
+        };
+        let namespace = owner.to_string();
+        let repo = repo.strip_suffix(".git").unwrap_or(repo).to_string();
+
+        let repo = match self.auth.find_repo(owner, &repo).await {
+            Ok(repo) => repo,
+            Err(e) => {
+                tracing::error!("repo_fetch_error error={}", e);
+                let _ = session.disconnect(
+                    Disconnect::ServiceNotAvailable,
+                    "Repository not found",
+                    "",
+                );
+                return Err(russh::Error::Disconnect);
+            }
+        };
+
+        self.model = Some(repo.clone());
+        let operator = match &self.operator {
+            Some(user) => user,
+            None => {
+                let msg = "Authentication error: no authenticated user";
+                tracing::error!(
+                    "exec_no_authenticated_user channel={:?}",
+                    channel_id
+                );
+                let _ = session.disconnect(Disconnect::ByApplication, msg, "");
+                return Err(russh::Error::Disconnect);
+            }
+        };
+
+        let is_write = service == GitService::ReceivePack;
+        let has_permission = self
+            .auth
+            .check_repo_permission(operator, &repo, is_write)
+            .await;
+
+        if !has_permission {
+            let msg = format!(
+                "Access denied: user '{}' does not have {} permission for repository {}",
+                operator.username,
+                if is_write { "write" } else { "read" },
+                repo.name
+            );
+            tracing::error!(
+                "access_denied user={} repo={} is_write={}",
+                operator.username,
+                repo.name,
+                is_write
+            );
+            let _ = session.disconnect(Disconnect::ByApplication, &msg, "");
+            return Err(russh::Error::Disconnect);
+        }
+
+        tracing::info!(
+            "access_granted user={} repo={} is_write={}",
+            operator.username,
+            repo.name,
+            is_write
+        );
+
+        let mut push_queue_lease = if is_write {
+            let repo_id = repo.id;
+            let queue_result =
+                wait_for_push_queue_slot(self.sync.clone(), repo_id, |event, request_id| {
+                    let request_id = request_id.to_string();
+                    match event {
+                        PushQueueEvent::Waiting(position) => {
+                            let msg = format!(
+                                "remote: another push is running for this repository. Queued {}/{}.\r\n",
+                                position.position, position.total
+                            );
+                            let _ = session.extended_data(channel_id, 1, msg.as_bytes().to_vec());
+                            let _ = session.flush();
+                            tracing::info!(
+                                repo_id = %repo_id,
+                                request_id = %request_id,
+                                position = position.position,
+                                total = position.total,
+                                "push_queue_waiting"
+                            );
+                        }
+                        PushQueueEvent::Acquired => {
+                            let msg = "remote: push queue slot acquired. Processing now.\r\n";
+                            let _ = session.extended_data(channel_id, 1, msg.as_bytes().to_vec());
+                            let _ = session.flush();
+                            tracing::info!(
+                                repo_id = %repo_id,
+                                request_id = %request_id,
+                                "push_queue_acquired"
+                            );
+                        }
+                    }
+                })
+                .await;
+
+            match queue_result {
+                Ok(lease) => Some(lease),
+                Err(error) => {
+                    match &error {
+                        PushQueueWaitError::Join(e) => {
+                            tracing::error!(error = %e, repo = %repo.name, "push_queue_join_failed");
+                            let msg = "remote: push queue is temporarily unavailable. Please retry later.\r\n";
+                            let _ = session.extended_data(
+                                channel_id,
+                                1,
+                                msg.as_bytes().to_vec(),
+                            );
+                        }
+                        PushQueueWaitError::Lock(e) => {
+                            tracing::error!(error = %e, repo_id = %repo.id, "push_queue_lock_failed");
+                            let msg = "remote: push queue lock failed. Please retry later.\r\n";
+                            let _ = session.extended_data(
+                                channel_id,
+                                1,
+                                msg.as_bytes().to_vec(),
+                            );
+                        }
+                        PushQueueWaitError::Timeout => {
+                            tracing::warn!(repo_id = %repo.id, "push_queue_timeout");
+                            let msg = "remote: push queue timed out. Please retry in a moment.\r\n";
+                            let _ = session.extended_data(
+                                channel_id,
+                                1,
+                                msg.as_bytes().to_vec(),
+                            );
+                        }
+                    }
+                    let _ = session.channel_failure(channel_id);
+                    let _ = session.close(channel_id);
+                    self.cleanup_channel(channel_id);
+                    return if matches!(error, PushQueueWaitError::Timeout) {
+                        Ok(())
+                    } else {
+                        Err(russh::Error::IO(io::Error::new(
+                            io::ErrorKind::Other,
+                            error.to_string(),
+                        )))
+                    };
+                }
+            }
+        } else {
+            None
+        };
+
+        let repo = match &self.model {
+            Some(m) => m,
+            None => {
+                let msg = "Repository model not available";
+                tracing::error!("repo_model_missing");
+                let _ = session.disconnect(Disconnect::ByApplication, msg, "");
+                return Err(russh::Error::Disconnect);
+            }
+        };
+        let repo_path = PathBuf::from(&repo.storage_path);
+        if !repo_path.exists() {
+            tracing::error!("repo_path_not_found path={}", repo_path.display());
+        }
+        tracing::info!(
+            "spawn_git_process service={:?} path={}",
+            service,
+            repo_path.display()
+        );
+        let mut cmd = build_git_command(service, repo_path);
+
+        let mut shell = match cmd
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+        {
+            Ok(shell) => {
+                let _ = session.channel_success(channel_id);
+                shell
+            }
+            Err(e) => {
+                tracing::error!("process_spawn_failed error={}", e);
+                if let Some(lease) = &mut push_queue_lease {
+                    lease.release().await;
+                }
+                let _ = session.channel_failure(channel_id);
+                self.cleanup_channel(channel_id);
+                return Err(russh::Error::IO(e));
+            }
+        };
+        let session_handle = session.handle();
+        let stdin = match shell.stdin.take() {
+            Some(s) => s,
+            None => {
+                tracing::error!(
+                    "stdin pipe unavailable for channel={:?}",
+                    channel_id
+                );
+                if let Some(lease) = &mut push_queue_lease {
+                    lease.release().await;
+                }
+                let _ = session_handle.channel_failure(channel_id).await;
+                return Err(russh::Error::IO(io::Error::new(
+                    io::ErrorKind::Other,
+                    "stdin unavailable",
+                )));
+            }
+        };
+        self.stdin.insert(channel_id, stdin);
+        let mut shell_stdout = match shell.stdout.take() {
+            Some(s) => s,
+            None => {
+                tracing::error!(
+                    "stdout pipe unavailable for channel={:?}",
+                    channel_id
+                );
+                if let Some(lease) = &mut push_queue_lease {
+                    lease.release().await;
+                }
+                return Err(russh::Error::IO(io::Error::new(
+                    io::ErrorKind::Other,
+                    "stdout unavailable",
+                )));
+            }
+        };
+        let mut shell_stderr = match shell.stderr.take() {
+            Some(s) => s,
+            None => {
+                tracing::error!(
+                    "stderr pipe unavailable for channel={:?}",
+                    channel_id
+                );
+                if let Some(lease) = &mut push_queue_lease {
+                    lease.release().await;
+                }
+                return Err(russh::Error::IO(io::Error::new(
+                    io::ErrorKind::Other,
+                    "stderr unavailable",
+                )));
+            }
+        };
+
+        let (eof_tx, mut eof_rx) = tokio::sync::mpsc::channel::<bool>(10);
+        self.eof.insert(channel_id, eof_tx);
+        let refs_for_hints = Arc::new(Mutex::new(Vec::new()));
+        self.post_receive_refs
+            .insert(channel_id, refs_for_hints.clone());
+        let repo_uid = repo.id;
+        let repo_for_hints = repo.clone();
+        let namespace_for_hints = namespace.clone();
+        let should_sync = service == GitService::ReceivePack;
+        let sync = self.sync.clone();
+        let mut push_queue_lease = push_queue_lease;
+
+        let fut = async move {
+            tracing::info!(channel = ?channel_id, "git_task_started");
+
+            let mut stdout_done = false;
+            let mut stderr_done = false;
+
+            let stdout_fut = forward(
+                &session_handle,
+                channel_id,
+                &mut shell_stdout,
+                |handle, chan, data| async move { handle.data(chan, data).await },
+            );
+            tokio::pin!(stdout_fut);
+
+            let stderr_fut = forward(
+                &session_handle,
+                channel_id,
+                &mut shell_stderr,
+                |handle, chan, data| async move {
+                    handle.extended_data(chan, 1, data).await
+                },
+            );
+            tokio::pin!(stderr_fut);
+
+            loop {
+                tokio::select! {
+                    result = shell.wait() => {
+                        let status = match result {
+                            Ok(status) => status,
+                            Err(e) => {
+                                if let Some(lease) = &mut push_queue_lease {
+                                    lease.release().await;
+                                }
+                                return Err(russh::Error::IO(e));
+                            }
+                        };
+                        let status_code = status.code().unwrap_or(128) as u32;
+
+                        tracing::info!("git_process_exited channel={:?} status={}", channel_id, status_code);
+
+                        if let Some(lease) = &mut push_queue_lease {
+                            lease.release().await;
+                        }
+
+                        if !stdout_done || !stderr_done {
+                            let _ = tokio::time::timeout(Duration::from_millis(100), async {
+                                tokio::join!(
+                                    async {
+                                        if !stdout_done {
+                                            let _ = (&mut stdout_fut).await;
+                                        }
+                                    },
+                                    async {
+                                        if !stderr_done {
+                                            let _ = (&mut stderr_fut).await;
+                                        }
+                                    }
+                                );
+                            }).await;
+                        }
+
+                        if should_sync && status_code == 0 {
+                            let queue = sync.send(RepoReceiveSyncTask { repo_uid }).await;
+                            let refs_for_hints = refs_for_hints.lock().await.clone();
+                            let msg = SSHandle::format_post_receive_hints(
+                                &namespace_for_hints,
+                                &repo_for_hints,
+                                &refs_for_hints,
+                                queue,
+                            );
+                            if !msg.is_empty() {
+                                let _ = session_handle
+                                    .extended_data(channel_id, 1, msg.into_bytes())
+                                    .await;
+                            }
+                        }
+
+                        let _ = session_handle.exit_status_request(channel_id, status_code).await;
+                        sleep(Duration::from_millis(50)).await;
+                        let _ = session_handle.eof(channel_id).await;
+                        let _ = session_handle.close(channel_id).await;
+                        tracing::info!(channel = ?channel_id, "channel_closed");
+                        break;
+                    }
+                    result = &mut stdout_fut, if !stdout_done => {
+                        tracing::info!("stdout completed");
+                        stdout_done = true;
+                        if let Err(e) = result {
+                            tracing::warn!(error = ?e, "stdout_forward_error");
+                        }
+                    }
+                    result = &mut stderr_fut, if !stderr_done => {
+                        tracing::info!("stderr completed");
+                        stderr_done = true;
+                        if let Err(e) = result {
+                            tracing::warn!(error = ?e, "stderr_forward_error");
+                        }
+                    }
+                }
+            }
+
+            Ok::<(), russh::Error>(())
+        };
+
+        tokio::spawn(async move {
+            if let Err(e) = fut.await {
+                tracing::error!("git_ssh_channel_task_error error={}", e);
+            }
+            while eof_rx.recv().await.is_some() {}
+        });
+        Ok(())
+    }
+}
diff --git a/lib/git/ssh/mod.rs b/lib/git/ssh/mod.rs
new file mode 100644
index 0000000..1e554f8
--- /dev/null
+++ b/lib/git/ssh/mod.rs
@@ -0,0 +1,195 @@
+use std::{sync::Arc, time::Duration};
+
+use anyhow::Context;
+use argon2::{
+    Argon2,
+    password_hash::{PasswordHash, PasswordVerifier},
+};
+use cache::AppCache;
+use config::AppConfig;
+use db::{database::AppDatabase, sqlx};
+use deadpool_redis::cluster::Pool as RedisPool;
+use model::users::{UserModel, UserTokenModel};
+use russh::{
+    MethodKind, MethodSet, SshId,
+    server::{Config, Server},
+};
+
+use crate::errors::GitError;
+
+pub mod authz;
+pub mod branch_protect;
+pub mod forward;
+pub mod git_service;
+pub mod handler;
+pub mod rate_limit;
+pub mod ref_update;
+pub mod server;
+
+#[derive(Clone)]
+pub struct SSHHandle {
+    pub db: AppDatabase,
+    pub app: AppConfig,
+    pub cache: AppCache,
+    pub redis_pool: RedisPool,
+}
+
+impl SSHHandle {
+    pub fn new(
+        db: AppDatabase,
+        app: AppConfig,
+        cache: AppCache,
+        redis_pool: RedisPool,
+    ) -> Self {
+        SSHHandle {
+            db,
+            app,
+            cache,
+            redis_pool,
+        }
+    }
+
+    pub async fn run_ssh(&self) -> anyhow::Result<()> {
+        tracing::info!("SSH server starting");
+        let key_file = self.app.ssh_server_private_key_file()?;
+        if key_file.is_empty() {
+            return Err(anyhow::anyhow!(
+                "SSH server private key file is not configured (APP_SSH_SERVER_PRIVATE_KEY_FILE)"
+            ));
+        }
+
+        tracing::info!("Loading SSH private key from file: {}", key_file);
+
+        let private_key_pem = std::fs::read_to_string(&key_file)
+            .with_context(|| format!("Failed to read SSH private key file: {}", key_file))?;
+
+        let private_key = russh::keys::decode_secret_key(&private_key_pem, None)
+            .or_else(|e| {
+                tracing::info!("decode_secret_key failed: {}, trying from_openssh", e);
+                russh::keys::ssh_key::PrivateKey::from_openssh(&private_key_pem)
+                    .map_err(|e2| anyhow::anyhow!(
+                        "Failed to parse SSH private key from {}: decode_secret_key={}, from_openssh={}",
+                        key_file, e, e2
+                    ))
+            })?;
+
+        tracing::info!("SSH private key loaded");
+        let mut config = Config::default();
+        config.keys = vec![private_key];
+        let version = format!("SSH-2.0-Work {}", env!("CARGO_PKG_VERSION"));
+        config.server_id = SshId::Standard(version.into());
+        config.methods = MethodSet::empty();
+        config.methods.push(MethodKind::PublicKey);
+        config.methods.push(MethodKind::Password);
+        config.auth_rejection_time = Duration::from_secs(5);
+        config.inactivity_timeout = Some(Duration::from_secs(300));
+        config.keepalive_interval = Some(Duration::from_secs(60));
+        config.keepalive_max = 3;
+
+        tracing::info!(
+            "SSH server configured with methods: {:?}",
+            config.methods
+        );
+        let token_service = SshTokenService::new(self.db.clone());
+        let mut ssh_server = server::SSHServer::new(
+            self.db.clone(),
+            self.cache.clone(),
+            self.redis_pool.clone(),
+            token_service,
+        );
+
+        let _cleanup = ssh_server.rate_limiter.clone().start_cleanup();
+
+        let ssh_port = self.app.ssh_port()?;
+        let bind_addr = format!("0.0.0.0:{}", ssh_port);
+        let public_host = self.app.ssh_domain()?;
+        let msg = if ssh_port == 22 {
+            format!(
+                "SSH server listening on port 22. Please use port {} for SSH connections.",
+                ssh_port
+            )
+        } else {
+            format!(
+                "SSH server listening on port {} (public: {}). Please use port {} for SSH connections.",
+                ssh_port, public_host, ssh_port
+            )
+        };
+        tracing::info!("{}", msg);
+        ssh_server
+            .run_on_address(Arc::new(config), bind_addr)
+            .await?;
+        Ok(())
+    }
+}
+#[derive(Clone)]
+pub struct SshTokenService {
+    db: AppDatabase,
+}
+
+impl SshTokenService {
+    pub fn new(db: AppDatabase) -> Self {
+        Self { db }
+    }
+
+    pub async fn find_user_by_token(
+        &self,
+        token: &str,
+    ) -> Result<Option<UserModel>, GitError> {
+        let token_models = sqlx::query_as::<_, UserTokenModel>(
+            "SELECT id, user, name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at FROM user_token WHERE is_revoked = false",
+        )
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| GitError::Internal(e.to_string()))?;
+
+        for token_model in token_models {
+            if token_model
+                .expires_at
+                .map(|expires_at| expires_at < chrono::Utc::now())
+                .unwrap_or(false)
+            {
+                continue;
+            }
+
+            let Ok(hash) = PasswordHash::new(&token_model.token_hash) else {
+                tracing::warn!(
+                    token_id = token_model.id,
+                    "invalid stored SSH token hash"
+                );
+                continue;
+            };
+
+            if Argon2::default()
+                .verify_password(token.as_bytes(), &hash)
+                .is_err()
+            {
+                continue;
+            }
+
+            let user_model = sqlx::query_as::<_, UserModel>(
+                "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, last_sign_in_at, created_at, updated_at FROM \"user\" WHERE id = $1",
+            )
+                .bind(token_model.user)
+                .fetch_optional(self.db.reader())
+                .await
+                .map_err(|e| GitError::Internal(e.to_string()))?;
+
+            return Ok(user_model);
+        }
+
+        Ok(None)
+    }
+}
+
+pub async fn run_ssh(
+    config: AppConfig,
+    db: AppDatabase,
+    cache: AppCache,
+    redis_pool: RedisPool,
+) -> anyhow::Result<()> {
+    tracing::info!("SSH server initializing");
+    SSHHandle::new(db, config.clone(), cache, redis_pool)
+        .run_ssh()
+        .await?;
+    Ok(())
+}
diff --git a/lib/git/ssh/rate_limit.rs b/lib/git/ssh/rate_limit.rs
new file mode 100644
index 0000000..2b60a5f
--- /dev/null
+++ b/lib/git/ssh/rate_limit.rs
@@ -0,0 +1,114 @@
+use std::{
+    collections::HashMap,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+
+use tokio::{sync::RwLock, time::interval};
+
+#[derive(Debug, Clone)]
+pub struct RateLimitConfig {
+    pub requests_per_window: u32,
+    pub window_duration: Duration,
+}
+
+impl Default for RateLimitConfig {
+    fn default() -> Self {
+        Self {
+            requests_per_window: 100,
+            window_duration: Duration::from_secs(60),
+        }
+    }
+}
+
+#[derive(Debug)]
+struct RateLimitState {
+    count: u32,
+    reset_time: Instant,
+}
+
+#[derive(Debug, Clone)]
+pub struct RateLimiter {
+    limits: Arc<RwLock<HashMap<String, RateLimitState>>>,
+    config: RateLimitConfig,
+}
+
+impl RateLimiter {
+    pub fn new(config: RateLimitConfig) -> Self {
+        Self {
+            limits: Arc::new(RwLock::new(HashMap::new())),
+            config,
+        }
+    }
+
+    pub async fn is_allowed(&self, key: &str) -> bool {
+        let now = Instant::now();
+        let mut limits = self.limits.write().await;
+
+        let state =
+            limits
+                .entry(key.to_string())
+                .or_insert_with(|| RateLimitState {
+                    count: 0,
+                    reset_time: now + self.config.window_duration,
+                });
+
+        if now >= state.reset_time {
+            state.count = 0;
+            state.reset_time = now + self.config.window_duration;
+        }
+
+        if state.count >= self.config.requests_per_window {
+            return false;
+        }
+
+        state.count += 1;
+        true
+    }
+
+    pub fn start_cleanup(self: Arc<Self>) -> tokio::task::JoinHandle<()> {
+        tokio::spawn(async move {
+            let mut ticker = interval(Duration::from_secs(300));
+            loop {
+                ticker.tick().await;
+                let now = Instant::now();
+                let mut limits = self.limits.write().await;
+                limits.retain(|_, state| now < state.reset_time);
+            }
+        })
+    }
+}
+
+pub struct SshRateLimiter {
+    limiter: RateLimiter,
+}
+
+impl SshRateLimiter {
+    pub fn new() -> Self {
+        Self {
+            limiter: RateLimiter::new(RateLimitConfig::default()),
+        }
+    }
+
+    pub async fn is_user_allowed(&self, user_id: &str) -> bool {
+        self.limiter.is_allowed(&format!("user:{}", user_id)).await
+    }
+
+    pub async fn is_ip_allowed(&self, ip_address: &str) -> bool {
+        self.limiter.is_allowed(&format!("ip:{}", ip_address)).await
+    }
+
+    pub async fn is_repo_access_allowed(
+        &self,
+        user_id: &str,
+        repo_path: &str,
+    ) -> bool {
+        self.limiter
+            .is_allowed(&format!("repo_access:{}:{}", user_id, repo_path))
+            .await
+    }
+
+    pub fn start_cleanup(self: Arc<Self>) -> tokio::task::JoinHandle<()> {
+        RateLimiter::start_cleanup(Arc::new(self.limiter.clone()))
+    }
+}
diff --git a/lib/git/ssh/ref_update.rs b/lib/git/ssh/ref_update.rs
new file mode 100644
index 0000000..0486b4f
--- /dev/null
+++ b/lib/git/ssh/ref_update.rs
@@ -0,0 +1,111 @@
+#[derive(Clone, Debug)]
+pub struct RefUpdate {
+    pub name: String,
+    pub old_oid: String,
+    pub new_oid: String,
+}
+
+impl RefUpdate {
+    pub fn parse_ref_updates(data: &[u8]) -> Result<Vec<Self>, String> {
+        let mut refs = Vec::new();
+
+        for payload in parse_pkt_line_payloads(data)? {
+            let line = String::from_utf8_lossy(payload);
+            let line = line.trim_end_matches(['\r', '\n']);
+            if line.is_empty() {
+                continue;
+            }
+
+            let mut parts = line.splitn(3, ' ');
+            let old_oid = parts.next().unwrap_or_default();
+            let new_oid = parts.next().unwrap_or_default();
+            let raw_name = parts.next().unwrap_or_default();
+            let name = raw_name
+                .split_once('\0')
+                .map(|(name, _)| name)
+                .unwrap_or(raw_name)
+                .trim();
+
+            if old_oid.len() != 40 || new_oid.len() != 40 || name.is_empty() {
+                continue;
+            }
+
+            refs.push(RefUpdate {
+                old_oid: old_oid.to_string(),
+                new_oid: new_oid.to_string(),
+                name: name.to_string(),
+            });
+        }
+
+        Ok(refs)
+    }
+}
+
+fn parse_pkt_line_payloads(data: &[u8]) -> Result<Vec<&[u8]>, String> {
+    let mut payloads = Vec::new();
+    let mut offset = 0;
+
+    while offset + 4 <= data.len() {
+        let header = std::str::from_utf8(&data[offset..offset + 4])
+            .map_err(|_| "invalid pkt-line header encoding".to_string())?;
+        let len = usize::from_str_radix(header, 16)
+            .map_err(|_| format!("invalid pkt-line length: {header}"))?;
+        offset += 4;
+
+        match len {
+            0 => break,
+            1..=3 => return Err(format!("invalid pkt-line length: {len}")),
+            _ => {
+                let payload_len = len - 4;
+                if offset + payload_len > data.len() {
+                    return Err("truncated pkt-line payload".to_string());
+                }
+                payloads.push(&data[offset..offset + payload_len]);
+                offset += payload_len;
+            }
+        }
+    }
+
+    Ok(payloads)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::RefUpdate;
+
+    fn pkt(payload: &str) -> Vec<u8> {
+        let len = payload.len() + 4;
+        let mut out = format!("{len:04x}").into_bytes();
+        out.extend_from_slice(payload.as_bytes());
+        out
+    }
+
+    #[test]
+    fn parses_receive_pack_ref_with_capabilities() {
+        let mut data = pkt(
+            "0000000000000000000000000000000000000000 1111111111111111111111111111111111111111 refs/heads/feature\0 report-status\n",
+        );
+        data.extend_from_slice(b"0000");
+
+        let refs = RefUpdate::parse_ref_updates(&data).unwrap();
+
+        assert_eq!(refs.len(), 1);
+        assert_eq!(refs[0].old_oid, "0000000000000000000000000000000000000000");
+        assert_eq!(refs[0].new_oid, "1111111111111111111111111111111111111111");
+        assert_eq!(refs[0].name, "refs/heads/feature");
+    }
+
+    #[test]
+    fn parses_receive_pack_ref_without_pack_payload() {
+        let mut data = pkt(
+            "2222222222222222222222222222222222222222 0000000000000000000000000000000000000000 refs/heads/old\n",
+        );
+        data.extend_from_slice(b"0000");
+
+        let refs = RefUpdate::parse_ref_updates(&data).unwrap();
+
+        assert_eq!(refs.len(), 1);
+        assert_eq!(refs[0].name, "refs/heads/old");
+        assert_eq!(refs[0].new_oid, "0000000000000000000000000000000000000000");
+    }
+}
diff --git a/lib/git/ssh/server.rs b/lib/git/ssh/server.rs
new file mode 100644
index 0000000..47bc127
--- /dev/null
+++ b/lib/git/ssh/server.rs
@@ -0,0 +1,98 @@
+use std::{io, net::SocketAddr, sync::Arc};
+
+use cache::AppCache;
+use db::database::AppDatabase;
+use deadpool_redis::cluster::Pool as RedisPool;
+use russh::server::Handler;
+
+use crate::{
+    ssh::{SshTokenService, handler::SSHandle, rate_limit::SshRateLimiter},
+    sync::ReceiveSyncService,
+};
+
+pub struct SSHServer {
+    pub db: AppDatabase,
+    pub cache: AppCache,
+    pub redis_pool: RedisPool,
+    pub token_service: SshTokenService,
+    pub rate_limiter: Arc<SshRateLimiter>,
+}
+
+impl SSHServer {
+    pub fn new(
+        db: AppDatabase,
+        cache: AppCache,
+        redis_pool: RedisPool,
+        token_service: SshTokenService,
+    ) -> Self {
+        SSHServer {
+            db,
+            cache,
+            redis_pool,
+            token_service,
+            rate_limiter: Arc::new(SshRateLimiter::new()),
+        }
+    }
+}
+
+impl russh::server::Server for SSHServer {
+    type Handler = SSHandle;
+
+    fn new_client(&mut self, addr: Option<SocketAddr>) -> Self::Handler {
+        if let Some(addr) = addr {
+            let ip = addr.ip().to_string();
+            tracing::info!("New SSH connection ip={} port={}", ip, addr.port());
+            let limiter = self.rate_limiter.clone();
+            let ip_clone = ip.clone();
+            tokio::spawn(async move {
+                if !limiter.is_ip_allowed(&ip_clone).await {
+                    tracing::warn!(ip = %ip_clone, "SSH connection rate limited");
+                }
+            });
+        } else {
+            tracing::info!("New SSH connection from unknown address");
+        }
+        let sync_service = ReceiveSyncService::new(self.redis_pool.clone());
+        SSHandle::new(
+            self.db.clone(),
+            self.cache.clone(),
+            sync_service,
+            self.token_service.clone(),
+            addr,
+        )
+    }
+
+    fn handle_session_error(
+        &mut self,
+        error: <Self::Handler as Handler>::Error,
+    ) {
+        match error {
+            russh::Error::Disconnect => {
+                tracing::info!("Connection disconnected by peer");
+            }
+            russh::Error::Inconsistent => {
+                tracing::warn!("Protocol inconsistency detected");
+            }
+            russh::Error::NotAuthenticated => {
+                tracing::warn!("Authentication failed");
+            }
+            russh::Error::IO(ref io_err) => {
+                tracing::warn!(
+                    "SSH IO error kind={:?} message={} raw_os_error={:?}",
+                    io_err.kind(),
+                    io_err,
+                    io_err.raw_os_error()
+                );
+
+                if io_err.kind() == io::ErrorKind::UnexpectedEof {
+                    tracing::warn!(
+                        "SSH peer closed the connection before a clean disconnect was received"
+                    );
+                }
+            }
+            _ => {
+                tracing::warn!("SSH session error error={}", error);
+            }
+        }
+    }
+}
diff --git a/lib/git/sync/branch.rs b/lib/git/sync/branch.rs
new file mode 100644
index 0000000..dbf9c1b
--- /dev/null
+++ b/lib/git/sync/branch.rs
@@ -0,0 +1,163 @@
+use std::collections::HashSet;
+
+use db::{database::AppDatabase, sqlx};
+use model::repos::RepoRefModel;
+use uuid::Uuid;
+
+use crate::{bare::GitBare, errors::GitError};
+#[derive(Debug, Clone)]
+pub struct BranchTip {
+    pub name: String,
+    pub shorthand: String,
+    pub target_oid: String,
+}
+pub fn collect_branch_tips(bare: &GitBare) -> Result<Vec<BranchTip>, GitError> {
+    let repo = bare.gix_repo()?;
+    let refs = repo.references()
+        .map_err(|e| GitError::Internal(format!("failed to open references: {}", e)))?;
+    let iter = refs.all()
+        .map_err(|e| GitError::Internal(format!("failed to iterate refs: {}", e)))?;
+
+    let mut branches = Vec::new();
+    for ref_result in iter {
+        let reference = ref_result
+            .map_err(|e| GitError::Internal(format!("ref iteration error: {}", e)))?;
+        let full_name = reference.name().as_bstr().to_string();
+        if !full_name.starts_with("refs/heads/") {
+            continue;
+        }
+        let target_oid = reference.target().try_id()
+            .map(|id| id.to_hex().to_string())
+            .ok_or_else(|| GitError::Internal("ref has no direct target".to_string()))?;
+        let shorthand = reference.name().shorten().to_string();
+        branches.push(BranchTip {
+            name: full_name,
+            shorthand,
+            target_oid,
+        });
+    }
+    Ok(branches)
+}
+pub async fn sync_refs(
+    db: &AppDatabase,
+    bare: &GitBare,
+    repo_id: Uuid,
+) -> Result<(), GitError> {
+    let now = chrono::Utc::now();
+    let pool = db.writer();
+
+    let existing: Vec<RepoRefModel> = sqlx::query_as::<_, RepoRefModel>(
+        "SELECT id, repo, name, kind, target_sha, is_default, is_protected, created_at, updated_at FROM repo_ref WHERE repo = $1 AND kind = 'branch'"
+    )
+        .bind(repo_id)
+        .fetch_all(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to query branches: {}", e)))?;
+
+    let mut existing_names: HashSet<String> =
+        existing.iter().map(|r| r.name.clone()).collect();
+
+    let branches = collect_branch_tips(bare)?;
+
+    const PREFERRED_BRANCHES: &[&str] = &["main", "master", "trunk"];
+
+    let current_default: Option<String> = sqlx::query_scalar::<_, String>(
+        "SELECT default_branch FROM repo WHERE id = $1",
+    )
+    .bind(repo_id)
+    .fetch_optional(pool)
+    .await
+    .map_err(|e| GitError::Internal(format!("failed to re-read repo: {}", e)))?
+    .filter(|b| !b.is_empty());
+
+    let mut auto_detected_branch: Option<String> = None;
+    if current_default.is_none() {
+        for preferred in PREFERRED_BRANCHES {
+            if branches.iter().any(|b| b.shorthand == *preferred) {
+                auto_detected_branch = Some((*preferred).to_string());
+                break;
+            }
+        }
+        if auto_detected_branch.is_none() {
+            if let Some(first) = branches.first() {
+                auto_detected_branch = Some(first.shorthand.clone());
+            }
+        }
+    }
+
+    for branch in &branches {
+        if existing_names.contains(&branch.name) {
+            existing_names.remove(&branch.name);
+            sqlx::query(
+                "UPDATE repo_ref SET target_sha = $1, updated_at = $2 WHERE repo = $3 AND name = $4 AND kind = 'branch'"
+            )
+                .bind(&branch.target_oid)
+                .bind(now)
+                .bind(repo_id)
+                .bind(&branch.name)
+                .execute(pool)
+                .await
+                .map_err(|e| GitError::Internal(format!("failed to update branch: {}", e)))?;
+        } else {
+            let new_id = Uuid::new_v4();
+            sqlx::query(
+                "INSERT INTO repo_ref (id, repo, name, kind, target_sha, is_default, is_protected, created_at, updated_at) VALUES ($1, $2, $3, 'branch', $4, $5, false, $6, $7)"
+            )
+                .bind(new_id)
+                .bind(repo_id)
+                .bind(&branch.name)
+                .bind(&branch.target_oid)
+                .bind(false)
+                .bind(now)
+                .bind(now)
+                .execute(pool)
+                .await
+                .map_err(|e| GitError::Internal(format!("failed to insert branch: {}", e)))?;
+        }
+    }
+
+    if !existing_names.is_empty() {
+        let names_vec: Vec<String> = existing_names.into_iter().collect();
+        sqlx::query("DELETE FROM repo_ref WHERE repo = $1 AND name = ANY($2) AND kind = 'branch'")
+            .bind(repo_id)
+            .bind(&names_vec)
+            .execute(pool)
+            .await
+            .map_err(|e| GitError::Internal(format!("failed to delete stale branches: {}", e)))?;
+    }
+
+    if let Some(ref branch_name) = auto_detected_branch {
+        let result = sqlx::query(
+            "UPDATE repo SET default_branch = $1, updated_at = $2 WHERE id = $3 AND default_branch = ''"
+        )
+            .bind(branch_name.clone())
+            .bind(now)
+            .bind(repo_id)
+            .execute(pool)
+            .await
+            .map_err(|e| GitError::Internal(format!("failed to set default branch: {}", e)))?;
+
+        if result.rows_affected() > 0 {
+            sqlx::query(
+                "UPDATE repo_ref SET is_default = false, updated_at = $1 WHERE repo = $2 AND kind = 'branch'"
+            )
+                .bind(now)
+                .bind(repo_id)
+                .execute(pool)
+                .await
+                .map_err(|e| GitError::Internal(format!("failed to clear head flags: {}", e)))?;
+
+            sqlx::query(
+                "UPDATE repo_ref SET is_default = true, updated_at = $1 WHERE repo = $2 AND name = $3 AND kind = 'branch'"
+            )
+                .bind(now)
+                .bind(repo_id)
+                .bind(branch_name)
+                .execute(pool)
+                .await
+                .map_err(|e| GitError::Internal(format!("failed to set head flag: {}", e)))?;
+        }
+    }
+
+    Ok(())
+}
diff --git a/lib/git/sync/cicheck.rs b/lib/git/sync/cicheck.rs
new file mode 100644
index 0000000..28008fd
--- /dev/null
+++ b/lib/git/sync/cicheck.rs
@@ -0,0 +1,157 @@
+use deadpool_redis::cluster::Pool as RedisPool;
+use parsefile::{Pipeline, TriggerEvent};
+
+use crate::{
+    bare::GitBare,
+    errors::GitError,
+    sync::{HookTask, TaskType},
+};
+
+const PIPELINE_FILE: &str = "pipeline.yaml";
+#[derive(Debug)]
+pub enum CiCheckOutcome {
+    Enqueued,
+    NoPipelineFile,
+    NotTriggered,
+}
+fn ci_queue_keys(repo_id: uuid::Uuid) -> (String, String) {
+    let hash_tag = format!("{{ci:{}}}", repo_id);
+    (
+        format!("{}:pending", hash_tag),
+        format!("{}:processing", hash_tag),
+    )
+}
+pub async fn check_and_enqueue(
+    bare: &GitBare,
+    repo_id: uuid::Uuid,
+    event: &TriggerEvent,
+    redis_pool: &RedisPool,
+) -> Result<CiCheckOutcome, GitError> {
+    let output = bare.git_command_trusted_stdout(vec![
+        "show".to_string(),
+        format!("HEAD:{}", PIPELINE_FILE),
+    ]);
+
+    let content = match output {
+        Ok(c) => c,
+        Err(_) => return Ok(CiCheckOutcome::NoPipelineFile),
+    };
+
+    let pipeline = parsefile::parse_from_str(&content).map_err(|e| {
+        GitError::Internal(format!("failed to parse {}: {}", PIPELINE_FILE, e))
+    })?;
+
+    if !pipeline.should_run(event) {
+        return Ok(CiCheckOutcome::NotTriggered);
+    }
+
+    enqueue_ci_task(repo_id, event, &pipeline, redis_pool)
+        .await
+        .map_err(|e| {
+            GitError::Internal(format!("failed to enqueue CI task: {}", e))
+        })?;
+
+    Ok(CiCheckOutcome::Enqueued)
+}
+
+async fn enqueue_ci_task(
+    repo_id: uuid::Uuid,
+    event: &TriggerEvent,
+    pipeline: &Pipeline,
+    redis_pool: &RedisPool,
+) -> Result<(), String> {
+    let hook_task = HookTask {
+        id: uuid::Uuid::new_v4().to_string(),
+        repo_id: repo_id.to_string(),
+        task_type: TaskType::Sync,
+        payload: serde_json::json!({
+            "ci": true,
+            "pipeline_name": pipeline.name,
+            "trigger": event_variant_name(event),
+        }),
+        created_at: chrono::Utc::now(),
+        retry_count: 0,
+    };
+
+    let task_json = serde_json::to_string(&hook_task)
+        .map_err(|e| format!("serialize error: {}", e))?;
+
+    let (pending_key, _) = ci_queue_keys(repo_id);
+
+    let redis = redis_pool
+        .get()
+        .await
+        .map_err(|e| format!("redis pool: {}", e))?;
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+
+    redis::cmd("LPUSH")
+        .arg(&pending_key)
+        .arg(&task_json)
+        .query_async::<()>(&mut conn)
+        .await
+        .map_err(|e| format!("LPUSH error: {}", e))?;
+
+    tracing::info!(
+        repo_id = %repo_id,
+        pipeline = %pipeline.name,
+        trigger = %event_variant_name(event),
+        "CI task enqueued"
+    );
+
+    Ok(())
+}
+
+fn event_variant_name(event: &TriggerEvent) -> &'static str {
+    match event {
+        TriggerEvent::PushBranch(_) => "push_branch",
+        TriggerEvent::PushTag(_) => "push_tag",
+        TriggerEvent::PullRequest { .. } => "pull_request",
+    }
+}
+pub async fn poll_ci_task_for_repo(
+    redis_pool: &RedisPool,
+    repo_id: uuid::Uuid,
+    block_timeout_secs: usize,
+) -> Option<String> {
+    let (pending_key, processing_key) = ci_queue_keys(repo_id);
+
+    let redis = redis_pool.get().await.ok()?;
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+
+    redis::cmd("BLMOVE")
+        .arg(&pending_key)
+        .arg(&processing_key)
+        .arg("RIGHT")
+        .arg("LEFT")
+        .arg(block_timeout_secs)
+        .query_async::<Option<String>>(&mut conn)
+        .await
+        .ok()
+        .flatten()
+}
+pub async fn ack_ci_task(
+    redis_pool: &RedisPool,
+    repo_id: uuid::Uuid,
+    task_json: &str,
+) {
+    let (_, processing_key) = ci_queue_keys(repo_id);
+
+    let redis = match redis_pool.get().await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::warn!(error = %e, "CI ack: failed to get redis connection");
+            return;
+        }
+    };
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+
+    if let Err(e) = redis::cmd("LREM")
+        .arg(&processing_key)
+        .arg(1)
+        .arg(task_json)
+        .query_async::<()>(&mut conn)
+        .await
+    {
+        tracing::warn!(error = %e, "CI ack: LREM failed");
+    }
+}
diff --git a/lib/git/sync/commit.rs b/lib/git/sync/commit.rs
new file mode 100644
index 0000000..fde549f
--- /dev/null
+++ b/lib/git/sync/commit.rs
@@ -0,0 +1,195 @@
+use std::collections::{HashMap, HashSet};
+
+use chrono::{DateTime, Utc};
+use db::{database::AppDatabase, sqlx};
+use model::repos::RepoCommitterModel;
+use uuid::Uuid;
+
+use crate::{bare::GitBare, cmd::oid::ObjectId, errors::GitError};
+pub async fn sync_commits(
+    db: &AppDatabase,
+    bare: &GitBare,
+    repo_id: Uuid,
+) -> Result<(), GitError> {
+    let repo = bare.gix_repo()?;
+    let pool = db.writer();
+
+    let existing_oids: Vec<String> = sqlx::query_scalar::<_, String>(
+        "SELECT sha FROM repo_commit WHERE repo = $1",
+    )
+        .bind(repo_id)
+        .fetch_all(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to query commits: {}", e)))?;
+    let existing_set: HashSet<String> = existing_oids.into_iter().collect();
+
+    let head_id = repo.head_id()
+        .map_err(|e| GitError::Internal(format!("failed to resolve HEAD: {}", e)))?
+        .detach();
+
+    let tips = {
+        let refs = repo.references()
+            .map_err(|e| GitError::Internal(format!("failed to open references: {}", e)))?;
+        let iter = refs.all()
+            .map_err(|e| GitError::Internal(format!("failed to iterate refs: {}", e)))?;
+        let mut tips = vec![head_id];
+        for ref_result in iter {
+            let reference = ref_result
+                .map_err(|e| GitError::Internal(format!("ref iteration error: {}", e)))?;
+            let name = reference.name().as_bstr().to_string();
+            if !name.starts_with("refs/heads/") {
+                continue;
+            }
+            if let Some(target_id) = reference.target().try_id() {
+                let hex = target_id.to_hex().to_string();
+                if let Ok(gix_id) = gix::hash::ObjectId::from_hex(hex.as_bytes()) {
+                    tips.push(gix_id);
+                }
+            }
+        }
+        tips
+    };
+
+    let platform = repo.rev_walk(tips)
+        .sorting(gix::revision::walk::Sorting::ByCommitTime(
+            gix::traverse::commit::simple::CommitTimeOrder::NewestFirst,
+        ));
+    let walk = platform.all()
+        .map_err(|e| GitError::Internal(format!("rev_walk failed: {}", e)))?;
+
+    let mut new_commits: Vec<gix::hash::ObjectId> = Vec::new();
+    for info in walk {
+        let info = info.map_err(|e| GitError::Internal(format!("walk step error: {}", e)))?;
+        let hex = info.id().detach().to_hex().to_string();
+        if !existing_set.contains(&hex) {
+            new_commits.push(info.id().detach());
+        }
+    }
+
+    if new_commits.is_empty() {
+        return Ok(());
+    }
+    let mut committer_map: HashMap<String, (Uuid, String)> = HashMap::new(); // email → (committer_id, name)
+
+    let existing_committers: Vec<RepoCommitterModel> = sqlx::query_as::<_, RepoCommitterModel>(
+        "SELECT id, repo, \"user\", name, email, created_at, updated_at FROM repo_committer WHERE repo = $1",
+    )
+        .bind(repo_id)
+        .fetch_all(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to query repo_committer: {}", e)))?;
+
+    for model in &existing_committers {
+        committer_map.insert(model.email.clone(), (model.id, model.name.clone()));
+    }
+
+    let email_map = resolve_user_ids(db, &committer_map).await?;
+
+    let now = Utc::now();
+
+    for gix_id in &new_commits {
+        let hex_oid = gix_id.to_hex().to_string();
+        let oid = ObjectId::new(&hex_oid);
+        let commit_meta = bare.commit_info(oid)
+            .map_err(|e| GitError::Internal(format!("commit_info failed for {}: {}", hex_oid, e)))?;
+
+        let author_committer_id = ensure_committer(
+            &mut committer_map, pool, repo_id, &commit_meta.author.email,
+            &commit_meta.author.name, &email_map, now,
+        ).await?;
+        let committer_committer_id = ensure_committer(
+            &mut committer_map, pool, repo_id, &commit_meta.committer.email,
+            &commit_meta.committer.name, &email_map, now,
+        ).await?;
+
+        let parent_shas = commit_meta.parent_ids
+            .iter()
+            .map(|p| p.as_str())
+            .collect::<Vec<_>>()
+            .join(".");
+        let authored_at = git_time_to_datetime(commit_meta.author.time_secs, commit_meta.author.offset_minutes);
+        let committed_at = git_time_to_datetime(commit_meta.committer.time_secs, commit_meta.committer.offset_minutes);
+
+        let new_id = Uuid::new_v4();
+        sqlx::query(
+            "INSERT INTO repo_commit (id, repo, sha, tree_sha, parent_shas, author, committer, message, authored_at, committed_at, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)"
+        )
+            .bind(new_id)
+            .bind(repo_id)
+            .bind(&hex_oid)
+            .bind(commit_meta.tree_id.as_str())
+            .bind(&parent_shas)
+            .bind(author_committer_id)
+            .bind(committer_committer_id)
+            .bind(&commit_meta.message)
+            .bind(authored_at)
+            .bind(committed_at)
+            .bind(now)
+            .execute(pool)
+            .await
+            .map_err(|e| GitError::Internal(format!("failed to insert commit: {}", e)))?;
+    }
+
+    Ok(())
+}
+
+async fn resolve_user_ids(
+    db: &AppDatabase,
+    committer_map: &HashMap<String, (Uuid, String)>,
+) -> Result<HashMap<String, Uuid>, GitError> {
+    if committer_map.is_empty() {
+        return Ok(HashMap::new());
+    }
+    let pool = db.writer();
+    let email_vec: Vec<String> = committer_map.keys().cloned().collect();
+
+    let rows: Vec<(Uuid, String)> = sqlx::query_as(
+        "SELECT \"user\", email FROM user_email WHERE email = ANY($1) AND active = true",
+    )
+        .bind(&email_vec)
+        .fetch_all(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to query user emails: {}", e)))?;
+
+    let mut map = HashMap::new();
+    for (user_id, email) in rows {
+        map.insert(email, user_id);
+    }
+    Ok(map)
+}
+async fn ensure_committer(
+    committer_map: &mut HashMap<String, (Uuid, String)>,
+    pool: &sqlx::Pool<sqlx::Postgres>,
+    repo_id: Uuid,
+    email: &str,
+    name: &str,
+    email_map: &HashMap<String, Uuid>,
+    now: DateTime<Utc>,
+) -> Result<Uuid, GitError> {
+    if let Some((id, _)) = committer_map.get(email) {
+        return Ok(*id);
+    }
+    let user_id = email_map.get(email).copied();
+    let new_id = Uuid::new_v4();
+    sqlx::query(
+        "INSERT INTO repo_committer (id, repo, \"user\", name, email, created_at, updated_at) \
+         VALUES ($1, $2, $3, $4, $5, $6, $7)"
+    )
+        .bind(new_id)
+        .bind(repo_id)
+        .bind(user_id)
+        .bind(name)
+        .bind(email)
+        .bind(now)
+        .bind(now)
+        .execute(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to insert repo_committer: {}", e)))?;
+    committer_map.insert(email.to_string(), (new_id, name.to_string()));
+    Ok(new_id)
+}
+fn git_time_to_datetime(secs: i64, offset_minutes: i32) -> DateTime<Utc> {
+    let utc_secs = secs - (offset_minutes as i64 * 60);
+    DateTime::from_timestamp(utc_secs, 0).unwrap_or_else(|| Utc::now())
+}
diff --git a/lib/git/sync/consumer.rs b/lib/git/sync/consumer.rs
new file mode 100644
index 0000000..66dd820
--- /dev/null
+++ b/lib/git/sync/consumer.rs
@@ -0,0 +1,90 @@
+use deadpool_redis::cluster::Connection;
+use redis::AsyncCommands;
+
+use crate::sync::{ReceiveSyncService, TaskType};
+pub struct SyncConsumer {
+    service: ReceiveSyncService,
+    block_timeout_secs: u64,
+}
+
+impl SyncConsumer {
+    pub fn new(service: ReceiveSyncService, block_timeout_secs: u64) -> Self {
+        Self {
+            service,
+            block_timeout_secs,
+        }
+    }
+    pub async fn next(&self, task_type: &TaskType) -> Option<(String, String)> {
+        let prefix = &self.service.redis_prefix;
+        let queue_key = match task_type {
+            TaskType::Sync => format!("{prefix}:sync"),
+            TaskType::Fsck => format!("{prefix}:fsck"),
+            TaskType::Gc => format!("{prefix}:gc"),
+            TaskType::Webhook => format!("{prefix}:webhook"),
+        };
+        let work_key = format!("{queue_key}:work");
+
+        let redis = self.service.pool.get().await.ok()?;
+        let mut conn: Connection = redis;
+
+        let result: Option<String> = redis::cmd("BLMOVE")
+            .arg(&queue_key)
+            .arg(&work_key)
+            .arg("RIGHT")
+            .arg("LEFT")
+            .arg(self.block_timeout_secs)
+            .query_async(&mut conn)
+            .await
+            .ok()?;
+
+        result.map(|json| (json, work_key))
+    }
+    pub async fn ack(&self, task_json: &str, work_key: &str) -> Option<()> {
+        let redis = self.service.pool.get().await.ok()?;
+        let mut conn: Connection = redis;
+        let removed: i32 = conn.lrem(work_key, 1, task_json).await.ok()?;
+        if removed > 0 { Some(()) } else { None }
+    }
+    pub async fn nak_with_retry(
+        &self,
+        task_json: &str,
+        work_key: &str,
+        queue_key: &str,
+    ) -> Option<()> {
+        let redis = self.service.pool.get().await.ok()?;
+        let mut conn: Connection = redis;
+
+        let script = redis::Script::new(
+            r#"
+            local removed = redis.call("LREM", KEYS[1], 0, ARGV[1])
+            if removed > 0 then
+                redis.call("LPUSH", KEYS[2], ARGV[1])
+            end
+            return removed
+            "#,
+        );
+
+        let result: i32 = script
+            .key(work_key)
+            .key(queue_key)
+            .arg(task_json)
+            .invoke_async(&mut conn)
+            .await
+            .ok()?;
+
+        if result > 0 { Some(()) } else { None }
+    }
+
+    pub(crate) fn queue_key_for_task_type(
+        &self,
+        task_type: &TaskType,
+    ) -> String {
+        let prefix = &self.service.redis_prefix;
+        match task_type {
+            TaskType::Sync => format!("{prefix}:sync"),
+            TaskType::Fsck => format!("{prefix}:fsck"),
+            TaskType::Gc => format!("{prefix}:gc"),
+            TaskType::Webhook => format!("{prefix}:webhook"),
+        }
+    }
+}
diff --git a/lib/git/sync/language.rs b/lib/git/sync/language.rs
new file mode 100644
index 0000000..f82e73d
--- /dev/null
+++ b/lib/git/sync/language.rs
@@ -0,0 +1,176 @@
+use std::collections::HashMap;
+
+use db::{database::AppDatabase, sqlx};
+use uuid::Uuid;
+
+use crate::{bare::GitBare, cmd::oid::ObjectId, errors::GitError};
+fn language_from_extension(ext: &str) -> Option<&str> {
+    match ext {
+        "rs" => Some("Rust"),
+        "ts" | "tsx" => Some("TypeScript"),
+        "js" | "jsx" | "mjs" | "cjs" => Some("JavaScript"),
+        "py" | "pyi" => Some("Python"),
+        "go" => Some("Go"),
+        "java" => Some("Java"),
+        "kt" | "kts" => Some("Kotlin"),
+        "c" | "h" => Some("C"),
+        "cpp" | "cc" | "cxx" | "hpp" | "hxx" => Some("C++"),
+        "cs" => Some("C#"),
+        "rb" => Some("Ruby"),
+        "php" => Some("PHP"),
+        "swift" => Some("Swift"),
+        "scala" => Some("Scala"),
+        "lua" => Some("Lua"),
+        "r" | "R" => Some("R"),
+        "sql" => Some("SQL"),
+        "sh" | "bash" => Some("Shell"),
+        "ps1" => Some("PowerShell"),
+        "dart" => Some("Dart"),
+        "el" | "lisp" => Some("Emacs Lisp"),
+        "clj" | "cljs" => Some("Clojure"),
+        "hs" => Some("Haskell"),
+        "ex" | "exs" => Some("Elixir"),
+        "erl" => Some("Erlang"),
+        "vue" => Some("Vue"),
+        "svelte" => Some("Svelte"),
+        "css" | "scss" | "sass" | "less" => Some("CSS"),
+        "html" | "htm" => Some("HTML"),
+        "xml" | "xsl" | "xsd" => Some("XML"),
+        "json" | "jsonl" => Some("JSON"),
+        "yaml" | "yml" => Some("YAML"),
+        "toml" => Some("TOML"),
+        "md" | "markdown" => Some("Markdown"),
+        "dockerfile" => Some("Dockerfile"),
+        "proto" => Some("Protocol Buffers"),
+        "tf" => Some("HCL"),
+        "zig" => Some("Zig"),
+        "nim" => Some("Nim"),
+        "v" => Some("V"),
+        "wasm" => Some("WebAssembly"),
+        "glsl" => Some("GLSL"),
+        "cu" | "cuh" => Some("CUDA"),
+        "makefile" => Some("Makefile"),
+        _ => None,
+    }
+}
+fn language_from_filename(name: &str) -> Option<&str> {
+    let lower = name.to_ascii_lowercase();
+    match lower.as_str() {
+        "makefile" | "gnumakefile" => Some("Makefile"),
+        "dockerfile" => Some("Dockerfile"),
+        "cmakelists.txt" => Some("CMake"),
+        "cargo.toml" => Some("TOML"),
+        "package.json" => Some("JSON"),
+        "tsconfig.json" => Some("JSON"),
+        ".gitignore" | ".gitattributes" => Some("Gitignore"),
+        _ => None,
+    }
+}
+fn collect_language_stats(bare: &GitBare) -> Result<HashMap<String, u64>, GitError> {
+    let repo = bare.gix_repo()?;
+    let head_id = repo.head_id()
+        .map_err(|e| GitError::Internal(format!("failed to resolve HEAD: {}", e)))?;
+    let commit = repo.find_commit(head_id.detach())
+        .map_err(|e| GitError::Internal(format!("failed to find HEAD commit: {}", e)))?;
+    let decoded = commit.decode()
+        .map_err(|e| GitError::Internal(format!("failed to decode commit: {}", e)))?;
+    let tree_oid = ObjectId::new(decoded.tree().to_hex().to_string());
+
+    let mut stats: HashMap<String, u64> = HashMap::new();
+    walk_tree(bare, &tree_oid, &mut stats)?;
+    Ok(stats)
+}
+fn walk_tree(
+    bare: &GitBare,
+    tree_oid: &ObjectId,
+    stats: &mut HashMap<String, u64>,
+) -> Result<(), GitError> {
+    let entries = bare.tree_entries(tree_oid.clone())?;
+
+    for entry in entries {
+        if entry.kind == crate::cmd::tree::TreeKind::Tree {
+            walk_tree(bare, &entry.oid, stats)?;
+            continue;
+        }
+        if entry.kind == crate::cmd::tree::TreeKind::LfsPointer {
+            continue;
+        }
+        if entry.is_binary {
+            continue;
+        }
+
+        let language = language_from_filename(&entry.name)
+            .or_else(|| {
+                let ext = entry.name.rsplit('.').next().unwrap_or("");
+                language_from_extension(ext)
+            });
+
+        if let Some(lang) = language {
+            let size = blob_size(bare, &entry.oid)?;
+            *stats.entry(lang.to_string()).or_insert(0) += size;
+        }
+    }
+    Ok(())
+}
+fn blob_size(bare: &GitBare, oid: &ObjectId) -> Result<u64, GitError> {
+    let repo = bare.gix_repo()?;
+    let gix_id: gix::hash::ObjectId = oid.try_into()
+        .map_err(|e| GitError::Internal(format!("invalid oid: {}", e)))?;
+    let header = repo.find_header(gix_id)
+        .map_err(|e| GitError::Internal(format!("blob header not found: {}", e)))?;
+    Ok(header.size() as u64)
+}
+pub async fn sync_languages(
+    db: &AppDatabase,
+    bare: &GitBare,
+    repo_id: Uuid,
+) -> Result<(), GitError> {
+    let stats = collect_language_stats(bare)?;
+    if stats.is_empty() {
+        return Ok(());
+    }
+
+    let total_bytes: u64 = stats.values().sum();
+    let pool = db.writer();
+
+    let mut tx = pool.begin()
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to begin tx: {}", e)))?;
+
+    sqlx::query("DELETE FROM repo_language WHERE repo = $1")
+        .bind(repo_id)
+        .execute(&mut *tx)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to delete repo_language: {}", e)))?;
+
+    for (language, bytes) in &stats {
+        let percentage = if total_bytes > 0 {
+            (*bytes as f32 / total_bytes as f32) * 100.0
+        } else {
+            0.0
+        };
+        sqlx::query(
+            "INSERT INTO repo_language (repo, language, bytes, percentage) VALUES ($1, $2, $3, $4)"
+        )
+            .bind(repo_id)
+            .bind(language)
+            .bind(*bytes as i64)
+            .bind(percentage)
+            .execute(&mut *tx)
+            .await
+            .map_err(|e| GitError::Internal(format!("failed to insert repo_language: {}", e)))?;
+    }
+
+    tx.commit()
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to commit tx: {}", e)))?;
+
+    tracing::info!(
+        repo_id = %repo_id,
+        languages = stats.len(),
+        total_bytes,
+        "language stats synced"
+    );
+
+    Ok(())
+}
diff --git a/lib/git/sync/lfs.rs b/lib/git/sync/lfs.rs
new file mode 100644
index 0000000..010d48c
--- /dev/null
+++ b/lib/git/sync/lfs.rs
@@ -0,0 +1,106 @@
+use std::collections::HashSet;
+
+use db::{database::AppDatabase, sqlx};
+use model::repos::RepoLfsObjectModel;
+use uuid::Uuid;
+
+use crate::{bare::GitBare, errors::GitError};
+pub async fn sync_lfs_objects(
+    db: &AppDatabase,
+    bare: &GitBare,
+    repo_id: Uuid,
+) -> Result<(), GitError> {
+    let pool = db.writer();
+
+    let existing: Vec<RepoLfsObjectModel> = sqlx::query_as::<_, RepoLfsObjectModel>(
+        "SELECT repo, oid, size_bytes, storage_key, created_at FROM repo_lfs_object WHERE repo = $1"
+    )
+        .bind(repo_id)
+        .fetch_all(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to query lfs objects: {}", e)))?;
+
+    let mut existing_oids: HashSet<String> =
+        existing.into_iter().map(|o| o.oid).collect();
+
+    let lfs_dir = bare.bare_dir.join(".lfs").join("objects");
+    if !lfs_dir.exists() {
+        if !existing_oids.is_empty() {
+            let oids_vec: Vec<String> = existing_oids.into_iter().collect();
+            sqlx::query(
+                "DELETE FROM repo_lfs_object WHERE repo = $1 AND oid = ANY($2)",
+            )
+            .bind(repo_id)
+            .bind(&oids_vec)
+            .execute(pool)
+            .await
+            .map_err(|e| {
+                GitError::Internal(format!(
+                    "failed to delete stale lfs objects: {}",
+                    e
+                ))
+            })?;
+        }
+        return Ok(());
+    }
+
+    let now = chrono::Utc::now();
+    let mut new_objects: Vec<(String, i64, String)> = Vec::new();
+
+    if let Ok(prefix_entries) = std::fs::read_dir(&lfs_dir) {
+        for prefix_entry in prefix_entries.flatten() {
+            if let Ok(oid_entries) = std::fs::read_dir(prefix_entry.path()) {
+                for oid_entry in oid_entries.flatten() {
+                    let oid_str =
+                        oid_entry.file_name().to_string_lossy().to_string();
+                    if existing_oids.contains(&oid_str) {
+                        existing_oids.remove(&oid_str);
+                        continue;
+                    }
+
+                    let path = oid_entry.path();
+                    let size_bytes = match std::fs::metadata(&path) {
+                        Ok(meta) => meta.len() as i64,
+                        Err(_) => continue,
+                    };
+                    let storage_key = path.to_string_lossy().to_string();
+
+                    new_objects.push((oid_str, size_bytes, storage_key));
+                }
+            }
+        }
+    }
+
+    for (oid, size_bytes, storage_key) in &new_objects {
+        sqlx::query(
+            "INSERT INTO repo_lfs_object (repo, oid, size_bytes, storage_key, created_at) VALUES ($1, $2, $3, $4, $5)"
+        )
+            .bind(repo_id)
+            .bind(oid)
+            .bind(*size_bytes)
+            .bind(storage_key)
+            .bind(now)
+            .execute(pool)
+            .await
+            .map_err(|e| GitError::Internal(format!("failed to insert lfs object: {}", e)))?;
+    }
+
+    if !existing_oids.is_empty() {
+        let oids_vec: Vec<String> = existing_oids.into_iter().collect();
+        sqlx::query(
+            "DELETE FROM repo_lfs_object WHERE repo = $1 AND oid = ANY($2)",
+        )
+        .bind(repo_id)
+        .bind(&oids_vec)
+        .execute(pool)
+        .await
+        .map_err(|e| {
+            GitError::Internal(format!(
+                "failed to delete stale lfs objects: {}",
+                e
+            ))
+        })?;
+    }
+
+    Ok(())
+}
diff --git a/lib/git/sync/lock.rs b/lib/git/sync/lock.rs
new file mode 100644
index 0000000..4666109
--- /dev/null
+++ b/lib/git/sync/lock.rs
@@ -0,0 +1,58 @@
+use deadpool_redis::cluster::Pool as RedisPool;
+pub async fn acquire_repo_lock(
+    pool: &RedisPool,
+    repo_id: uuid::Uuid,
+    lock_value: &str,
+    ttl_secs: usize,
+) -> redis::RedisResult<bool> {
+    let lock_key = format!("git:repo:lock:{}", repo_id);
+    let redis = pool.get().await.map_err(|e| {
+        redis::RedisError::from((
+            redis::ErrorKind::Io,
+            "failed to get Redis connection",
+            e.to_string(),
+        ))
+    })?;
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+    let acquired: Option<String> = redis::cmd("SET")
+        .arg(&lock_key)
+        .arg(lock_value)
+        .arg("NX")
+        .arg("EX")
+        .arg(ttl_secs)
+        .query_async(&mut conn)
+        .await?;
+    Ok(acquired.is_some())
+}
+pub async fn release_repo_lock(
+    pool: &RedisPool,
+    repo_id: uuid::Uuid,
+    lock_value: &str,
+) {
+    let lock_key = format!("git:repo:lock:{}", repo_id);
+    let redis = match pool.get().await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::warn!(error = %e, repo_id = %repo_id, "lock_release_redis_connection_failed");
+            return;
+        }
+    };
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+    let script = redis::Script::new(
+        r#"
+        if redis.call("GET", KEYS[1]) == ARGV[1] then
+            redis.call("DEL", KEYS[1])
+            return 1
+        end
+        return 0
+        "#,
+    );
+    if let Err(e) = script
+        .key(&lock_key)
+        .arg(lock_value)
+        .invoke_async::<i32>(&mut conn)
+        .await
+    {
+        tracing::warn!(error = %e, repo_id = %repo_id, "lock_release_failed");
+    }
+}
diff --git a/lib/git/sync/mod.rs b/lib/git/sync/mod.rs
new file mode 100644
index 0000000..5906924
--- /dev/null
+++ b/lib/git/sync/mod.rs
@@ -0,0 +1,266 @@
+use deadpool_redis::cluster::Pool as RedisPool;
+use redis::AsyncCommands;
+
+pub mod branch;
+pub mod cicheck;
+pub mod commit;
+pub mod consumer;
+pub mod language;
+pub mod lfs;
+pub mod lock;
+pub mod push_queue;
+pub mod tag;
+pub mod webhook;
+pub mod worker;
+#[derive(Clone)]
+pub struct ReceiveSyncService {
+    pool: RedisPool,
+    redis_prefix: String,
+}
+
+impl ReceiveSyncService {
+    pub fn new(pool: RedisPool) -> Self {
+        Self {
+            pool,
+            redis_prefix: "{hook}".to_string(),
+        }
+    }
+
+    pub fn pool(&self) -> RedisPool {
+        self.pool.clone()
+    }
+
+    pub async fn queue_position(
+        &self,
+        repo_uid: uuid::Uuid,
+    ) -> Option<(usize, usize)> {
+        let queue_key = format!("{}:sync", self.redis_prefix);
+        let work_key = format!("{}:work", queue_key);
+        let redis = self.pool.get().await.ok()?;
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        let queue_items: Vec<String> =
+            conn.lrange(&queue_key, 0, -1).await.ok()?;
+        let work_items: Vec<String> =
+            conn.lrange(&work_key, 0, -1).await.unwrap_or_default();
+        let repo_id = repo_uid.to_string();
+        let queued_before = queue_items
+            .iter()
+            .rev()
+            .take_while(|item| {
+                serde_json::from_str::<HookTask>(item)
+                    .map(|task| task.repo_id != repo_id)
+                    .unwrap_or(true)
+            })
+            .count();
+        let total = work_items.len() + queue_items.len() + 1;
+        Some((work_items.len() + queued_before + 1, total))
+    }
+
+    pub(crate) fn push_queue_keys(repo_uid: uuid::Uuid) -> (String, String) {
+        let hash_tag = format!("{{push:{}}}", repo_uid);
+        (
+            format!("git:{}:queue", hash_tag),
+            format!("git:{}:lock", hash_tag),
+        )
+    }
+
+    pub async fn join_push_queue(
+        &self,
+        repo_uid: uuid::Uuid,
+        request_id: &str,
+    ) -> redis::RedisResult<()> {
+        let (queue_key, _) = Self::push_queue_keys(repo_uid);
+        let redis = self.pool.get().await.map_err(|e| {
+            redis::RedisError::from((
+                redis::ErrorKind::Io,
+                "failed to get Redis connection",
+                e.to_string(),
+            ))
+        })?;
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        redis::cmd("RPUSH")
+            .arg(&queue_key)
+            .arg(request_id)
+            .query_async::<()>(&mut conn)
+            .await
+    }
+
+    pub async fn push_queue_position(
+        &self,
+        repo_uid: uuid::Uuid,
+        request_id: &str,
+    ) -> Option<(usize, usize)> {
+        let (queue_key, _) = Self::push_queue_keys(repo_uid);
+        let redis = self.pool.get().await.ok()?;
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        let queue_items: Vec<String> =
+            conn.lrange(&queue_key, 0, -1).await.ok()?;
+        let position =
+            queue_items.iter().position(|item| item == request_id)? + 1;
+        Some((position, queue_items.len()))
+    }
+
+    pub async fn try_acquire_push_lock(
+        &self,
+        repo_uid: uuid::Uuid,
+        request_id: &str,
+        ttl_secs: usize,
+    ) -> redis::RedisResult<bool> {
+        let (_, lock_key) = Self::push_queue_keys(repo_uid);
+        let redis = self.pool.get().await.map_err(|e| {
+            redis::RedisError::from((
+                redis::ErrorKind::Io,
+                "failed to get Redis connection",
+                e.to_string(),
+            ))
+        })?;
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        let acquired: Option<String> = redis::cmd("SET")
+            .arg(&lock_key)
+            .arg(request_id)
+            .arg("NX")
+            .arg("EX")
+            .arg(ttl_secs)
+            .query_async(&mut conn)
+            .await?;
+        Ok(acquired.is_some())
+    }
+
+    pub async fn release_push_queue(
+        &self,
+        repo_uid: uuid::Uuid,
+        request_id: &str,
+    ) {
+        let (queue_key, lock_key) = Self::push_queue_keys(repo_uid);
+        let redis = match self.pool.get().await {
+            Ok(c) => c,
+            Err(e) => {
+                tracing::warn!(error = %e, repo_id = %repo_uid, "push_queue_release_redis_connection_failed");
+                return;
+            }
+        };
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        let script = redis::Script::new(
+            r#"
+            redis.call("LREM", KEYS[1], 0, ARGV[1])
+            if redis.call("GET", KEYS[2]) == ARGV[1] then
+                redis.call("DEL", KEYS[2])
+            end
+            return 1
+            "#,
+        );
+        if let Err(e) = script
+            .key(&queue_key)
+            .key(&lock_key)
+            .arg(request_id)
+            .invoke_async::<()>(&mut conn)
+            .await
+        {
+            tracing::warn!(error = %e, repo_id = %repo_uid, "push_queue_release_failed");
+        }
+    }
+
+    pub async fn refresh_push_lock(
+        &self,
+        repo_uid: uuid::Uuid,
+        request_id: &str,
+        ttl_secs: usize,
+    ) -> redis::RedisResult<bool> {
+        let (_, lock_key) = Self::push_queue_keys(repo_uid);
+        let redis = self.pool.get().await.map_err(|e| {
+            redis::RedisError::from((
+                redis::ErrorKind::Io,
+                "failed to get Redis connection",
+                e.to_string(),
+            ))
+        })?;
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        let refreshed: i32 = redis::Script::new(
+            r#"
+            if redis.call("GET", KEYS[1]) == ARGV[1] then
+                redis.call("EXPIRE", KEYS[1], ARGV[2])
+                return 1
+            end
+            return 0
+            "#,
+        )
+        .key(&lock_key)
+        .arg(request_id)
+        .arg(ttl_secs)
+        .invoke_async(&mut conn)
+        .await?;
+        Ok(refreshed == 1)
+    }
+
+    pub async fn send(
+        &self,
+        task: RepoReceiveSyncTask,
+    ) -> Option<(usize, usize)> {
+        let position = self.queue_position(task.repo_uid).await;
+        let hook_task = HookTask {
+            id: uuid::Uuid::new_v4().to_string(),
+            repo_id: task.repo_uid.to_string(),
+            task_type: TaskType::Sync,
+            payload: serde_json::Value::Null,
+            created_at: chrono::Utc::now(),
+            retry_count: 0,
+        };
+
+        let task_json = match serde_json::to_string(&hook_task) {
+            Ok(j) => j,
+            Err(e) => {
+                tracing::error!("failed to serialize hook task: {}", e);
+                return position;
+            }
+        };
+
+        let queue_key = format!("{}:sync", self.redis_prefix);
+
+        let redis = match self.pool.get().await {
+            Ok(c) => c,
+            Err(e) => {
+                tracing::error!("failed to get Redis connection: {}", e);
+                return position;
+            }
+        };
+
+        let mut conn: deadpool_redis::cluster::Connection = redis;
+        if let Err(e) = redis::cmd("LPUSH")
+            .arg(&queue_key)
+            .arg(&task_json)
+            .query_async::<()>(&mut conn)
+            .await
+        {
+            tracing::error!(
+                "failed to enqueue sync task repo_id={} error={}",
+                task.repo_uid,
+                e
+            );
+        } else {
+            tracing::info!(repo_id = %task.repo_uid, "hook task queued to Redis");
+        }
+        position
+    }
+}
+
+#[derive(Clone)]
+pub struct RepoReceiveSyncTask {
+    pub repo_uid: uuid::Uuid,
+}
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct HookTask {
+    pub id: String,
+    pub repo_id: String,
+    pub task_type: TaskType,
+    pub payload: serde_json::Value,
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    pub retry_count: usize,
+}
+
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub enum TaskType {
+    Sync,
+    Fsck,
+    Gc,
+    Webhook,
+}
diff --git a/lib/git/sync/push_queue.rs b/lib/git/sync/push_queue.rs
new file mode 100644
index 0000000..e40e059
--- /dev/null
+++ b/lib/git/sync/push_queue.rs
@@ -0,0 +1,202 @@
+use std::{
+    fmt,
+    time::{Duration, Instant},
+};
+
+use tokio::{task::JoinHandle, time::sleep};
+
+use crate::sync::ReceiveSyncService;
+
+pub const PUSH_QUEUE_TIMEOUT: Duration = Duration::from_secs(120);
+pub const PUSH_LOCK_TTL_SECS: usize = 300;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct PushQueuePosition {
+    pub position: usize,
+    pub total: usize,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum PushQueueEvent {
+    Waiting(PushQueuePosition),
+    Acquired,
+}
+
+#[derive(Debug)]
+pub enum PushQueueWaitError {
+    Join(redis::RedisError),
+    Lock(redis::RedisError),
+    Timeout,
+}
+
+impl fmt::Display for PushQueueWaitError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Join(e) => write!(f, "failed to join push queue: {e}"),
+            Self::Lock(e) => {
+                write!(f, "failed to acquire push queue lock: {e}")
+            }
+            Self::Timeout => write!(f, "push queue timed out"),
+        }
+    }
+}
+
+impl std::error::Error for PushQueueWaitError {}
+
+pub struct PushQueueLease {
+    service: ReceiveSyncService,
+    repo_uid: uuid::Uuid,
+    request_id: String,
+    heartbeat: Option<JoinHandle<()>>,
+    released: bool,
+}
+
+impl PushQueueLease {
+    fn new(
+        service: ReceiveSyncService,
+        repo_uid: uuid::Uuid,
+        request_id: String,
+    ) -> Self {
+        let heartbeat = Some(start_lock_heartbeat(
+            service.clone(),
+            repo_uid,
+            request_id.clone(),
+        ));
+        Self {
+            service,
+            repo_uid,
+            request_id,
+            heartbeat,
+            released: false,
+        }
+    }
+
+    pub fn request_id(&self) -> &str {
+        &self.request_id
+    }
+
+    pub async fn release(&mut self) {
+        if self.released {
+            return;
+        }
+        self.service
+            .release_push_queue(self.repo_uid, &self.request_id)
+            .await;
+        if let Some(heartbeat) = self.heartbeat.take() {
+            heartbeat.abort();
+        }
+        self.released = true;
+    }
+}
+
+impl Drop for PushQueueLease {
+    fn drop(&mut self) {
+        if self.released {
+            return;
+        }
+        if let Some(heartbeat) = self.heartbeat.take() {
+            heartbeat.abort();
+        }
+        let service = self.service.clone();
+        let repo_uid = self.repo_uid;
+        let request_id = self.request_id.clone();
+        tokio::spawn(async move {
+            service.release_push_queue(repo_uid, &request_id).await;
+        });
+    }
+}
+
+fn start_lock_heartbeat(
+    service: ReceiveSyncService,
+    repo_uid: uuid::Uuid,
+    request_id: String,
+) -> JoinHandle<()> {
+    tokio::spawn(async move {
+        let interval =
+            Duration::from_secs((PUSH_LOCK_TTL_SECS as u64 / 3).max(30));
+        loop {
+            sleep(interval).await;
+            match service
+                .refresh_push_lock(repo_uid, &request_id, PUSH_LOCK_TTL_SECS)
+                .await
+            {
+                Ok(true) => {}
+                Ok(false) => {
+                    tracing::warn!(
+                        repo_id = %repo_uid,
+                        request_id = %request_id,
+                        "push_queue_lock_lost"
+                    );
+                    break;
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        error = %e,
+                        repo_id = %repo_uid,
+                        request_id = %request_id,
+                        "push_queue_lock_refresh_failed"
+                    );
+                }
+            }
+        }
+    })
+}
+
+pub async fn wait_for_push_queue_slot<F>(
+    service: ReceiveSyncService,
+    repo_uid: uuid::Uuid,
+    mut on_event: F,
+) -> Result<PushQueueLease, PushQueueWaitError>
+where
+    F: FnMut(PushQueueEvent, &str),
+{
+    let request_id = uuid::Uuid::new_v4().to_string();
+    service
+        .join_push_queue(repo_uid, &request_id)
+        .await
+        .map_err(PushQueueWaitError::Join)?;
+
+    let deadline = Instant::now() + PUSH_QUEUE_TIMEOUT;
+    let mut last_position = None;
+
+    loop {
+        let position = service.push_queue_position(repo_uid, &request_id).await;
+        if let Some((position, total)) = position {
+            let position = PushQueuePosition { position, total };
+            if last_position != Some(position) && position.position > 1 {
+                on_event(PushQueueEvent::Waiting(position), &request_id);
+            }
+            last_position = Some(position);
+
+            if position.position == 1 {
+                match service
+                    .try_acquire_push_lock(
+                        repo_uid,
+                        &request_id,
+                        PUSH_LOCK_TTL_SECS,
+                    )
+                    .await
+                {
+                    Ok(true) => {
+                        on_event(PushQueueEvent::Acquired, &request_id);
+                        return Ok(PushQueueLease::new(
+                            service, repo_uid, request_id,
+                        ));
+                    }
+                    Ok(false) => {}
+                    Err(e) => {
+                        service.release_push_queue(repo_uid, &request_id).await;
+                        return Err(PushQueueWaitError::Lock(e));
+                    }
+                }
+            }
+        }
+
+        if Instant::now() >= deadline {
+            service.release_push_queue(repo_uid, &request_id).await;
+            return Err(PushQueueWaitError::Timeout);
+        }
+
+        sleep(Duration::from_secs(1)).await;
+    }
+}
diff --git a/lib/git/sync/tag.rs b/lib/git/sync/tag.rs
new file mode 100644
index 0000000..f69ea29
--- /dev/null
+++ b/lib/git/sync/tag.rs
@@ -0,0 +1,100 @@
+use std::collections::HashSet;
+
+use db::{database::AppDatabase, sqlx};
+use model::repos::RepoRefModel;
+use uuid::Uuid;
+
+use crate::{bare::GitBare, errors::GitError};
+#[derive(Debug, Clone)]
+pub struct TagTip {
+    pub name: String,
+    pub target_oid: String,
+}
+pub fn collect_tag_tips(bare: &GitBare) -> Result<Vec<TagTip>, GitError> {
+    let repo = bare.gix_repo()?;
+    let refs = repo.references()
+        .map_err(|e| GitError::Internal(format!("failed to open references: {}", e)))?;
+    let iter = refs.all()
+        .map_err(|e| GitError::Internal(format!("failed to iterate refs: {}", e)))?;
+
+    let mut tags = Vec::new();
+    for ref_result in iter {
+        let reference = ref_result
+            .map_err(|e| GitError::Internal(format!("ref iteration error: {}", e)))?;
+        let full_name = reference.name().as_bstr().to_string();
+        if !full_name.starts_with("refs/tags/") {
+            continue;
+        }
+        let target_oid = reference.target().try_id()
+            .map(|id| id.to_hex().to_string())
+            .ok_or_else(|| GitError::Internal("ref has no direct target".to_string()))?;
+        let short_name = reference.name().shorten().to_string();
+        tags.push(TagTip {
+            name: short_name,
+            target_oid,
+        });
+    }
+    Ok(tags)
+}
+pub async fn sync_tags(
+    db: &AppDatabase,
+    bare: &GitBare,
+    repo_id: Uuid,
+) -> Result<(), GitError> {
+    let pool = db.writer();
+
+    let existing: Vec<RepoRefModel> = sqlx::query_as::<_, RepoRefModel>(
+        "SELECT id, repo, name, kind, target_sha, is_default, is_protected, created_at, updated_at FROM repo_ref WHERE repo = $1 AND kind = 'tag'"
+    )
+        .bind(repo_id)
+        .fetch_all(pool)
+        .await
+        .map_err(|e| GitError::Internal(format!("failed to query tags: {}", e)))?;
+    let mut existing_names: HashSet<String> =
+        existing.iter().map(|t| t.name.clone()).collect();
+
+    let tags = collect_tag_tips(bare)?;
+    let now = chrono::Utc::now();
+
+    for tag in tags {
+        if existing_names.contains(&tag.name) {
+            existing_names.remove(&tag.name);
+            sqlx::query(
+                "UPDATE repo_ref SET target_sha = $1, updated_at = $2 WHERE repo = $3 AND name = $4 AND kind = 'tag'"
+            )
+                .bind(&tag.target_oid)
+                .bind(now)
+                .bind(repo_id)
+                .bind(&tag.name)
+                .execute(pool)
+                .await
+                .map_err(|e| GitError::Internal(format!("failed to update tag: {}", e)))?;
+        } else {
+            let new_id = Uuid::new_v4();
+            sqlx::query(
+                "INSERT INTO repo_ref (id, repo, name, kind, target_sha, is_default, is_protected, created_at, updated_at) VALUES ($1, $2, $3, 'tag', $4, false, false, $5, $6)"
+            )
+                .bind(new_id)
+                .bind(repo_id)
+                .bind(&tag.name)
+                .bind(&tag.target_oid)
+                .bind(now)
+                .bind(now)
+                .execute(pool)
+                .await
+                .map_err(|e| GitError::Internal(format!("failed to insert tag: {}", e)))?;
+        }
+    }
+
+    if !existing_names.is_empty() {
+        let names_vec: Vec<String> = existing_names.into_iter().collect();
+        sqlx::query("DELETE FROM repo_ref WHERE repo = $1 AND name = ANY($2) AND kind = 'tag'")
+            .bind(repo_id)
+            .bind(&names_vec)
+            .execute(pool)
+            .await
+            .map_err(|e| GitError::Internal(format!("failed to delete stale tags: {}", e)))?;
+    }
+
+    Ok(())
+}
diff --git a/lib/git/sync/webhook.rs b/lib/git/sync/webhook.rs
new file mode 100644
index 0000000..d798e9f
--- /dev/null
+++ b/lib/git/sync/webhook.rs
@@ -0,0 +1,194 @@
+use std::time::Duration;
+
+use deadpool_redis::cluster::Pool as RedisPool;
+use hmac::{Hmac, KeyInit, Mac};
+use sha2::Sha256;
+
+type HmacSha256 = Hmac<Sha256>;
+fn webhook_queue_keys(repo_id: uuid::Uuid) -> (String, String) {
+    let hash_tag = format!("{{wh:{}}}", repo_id);
+    (
+        format!("{}:pending", hash_tag),
+        format!("{}:processing", hash_tag),
+    )
+}
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct WebhookDeliveryTask {
+    pub id: String,
+    pub webhook_id: String,
+    pub repo_id: String,
+    pub event: String,
+    pub url: String,
+    pub secret: Option<String>,
+    pub payload: serde_json::Value,
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    pub retry_count: usize,
+}
+pub async fn enqueue_delivery(
+    task: WebhookDeliveryTask,
+    redis_pool: &RedisPool,
+) -> Result<(), String> {
+    let task_json = serde_json::to_string(&task)
+        .map_err(|e| format!("serialize error: {}", e))?;
+
+    let repo_id: uuid::Uuid = task
+        .repo_id
+        .parse()
+        .map_err(|e| format!("invalid repo_id: {}", e))?;
+    let (pending_key, _) = webhook_queue_keys(repo_id);
+
+    let redis = redis_pool
+        .get()
+        .await
+        .map_err(|e| format!("redis pool: {}", e))?;
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+
+    redis::cmd("LPUSH")
+        .arg(&pending_key)
+        .arg(&task_json)
+        .query_async::<()>(&mut conn)
+        .await
+        .map_err(|e| format!("LPUSH error: {}", e))?;
+
+    tracing::info!(
+        webhook_id = %task.webhook_id,
+        repo_id = %task.repo_id,
+        event = %task.event,
+        "webhook delivery enqueued"
+    );
+
+    Ok(())
+}
+pub async fn poll_delivery_for_repo(
+    redis_pool: &RedisPool,
+    repo_id: uuid::Uuid,
+    block_timeout_secs: usize,
+) -> Option<String> {
+    let (pending_key, processing_key) = webhook_queue_keys(repo_id);
+
+    let redis = redis_pool.get().await.ok()?;
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+
+    redis::cmd("BLMOVE")
+        .arg(&pending_key)
+        .arg(&processing_key)
+        .arg("RIGHT")
+        .arg("LEFT")
+        .arg(block_timeout_secs)
+        .query_async::<Option<String>>(&mut conn)
+        .await
+        .ok()
+        .flatten()
+}
+pub async fn ack_delivery(
+    redis_pool: &RedisPool,
+    repo_id: uuid::Uuid,
+    task_json: &str,
+) {
+    let (_, processing_key) = webhook_queue_keys(repo_id);
+
+    let redis = match redis_pool.get().await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::warn!(error = %e, "webhook ack: failed to get redis connection");
+            return;
+        }
+    };
+    let mut conn: deadpool_redis::cluster::Connection = redis;
+
+    if let Err(e) = redis::cmd("LREM")
+        .arg(&processing_key)
+        .arg(1)
+        .arg(task_json)
+        .query_async::<()>(&mut conn)
+        .await
+    {
+        tracing::warn!(error = %e, "webhook ack: LREM failed");
+    }
+}
+fn compute_hmac_signature(secret: &str, body: &[u8]) -> String {
+    let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
+        .expect("HMAC can take key of any size");
+    mac.update(body);
+    let result = mac.finalize();
+    let code_bytes = result.into_bytes();
+    hex::encode(code_bytes)
+}
+pub async fn deliver_webhook(
+    task: &WebhookDeliveryTask,
+) -> WebhookDeliveryResult {
+    let body_bytes = serde_json::to_vec(&task.payload).unwrap_or_default();
+
+    let signature = task
+        .secret
+        .as_ref()
+        .map(|s| compute_hmac_signature(s, &body_bytes));
+
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(10))
+        .build()
+        .unwrap_or_default();
+
+    let mut request = client
+        .post(&task.url)
+        .header("Content-Type", "application/json")
+        .header("X-GitData-Event", &task.event)
+        .header("X-GitData-Delivery", &task.id);
+
+    if let Some(sig) = &signature {
+        request = request
+            .header("X-GitData-Signature-256", format!("sha256={}", sig));
+    }
+
+    let response = request.body(body_bytes.clone()).send().await;
+
+    match response {
+        Ok(resp) => {
+            let status = resp.status().as_u16() as i32;
+            let resp_headers: String = resp
+                .headers()
+                .iter()
+                .map(|(k, v)| {
+                    format!("{}: {}", k, v.to_str().unwrap_or_default())
+                })
+                .collect::<Vec<_>>()
+                .join("\n");
+            let resp_body = resp.text().await.unwrap_or_default();
+
+            WebhookDeliveryResult {
+                response_status: Some(status),
+                response_headers: Some(resp_headers),
+                response_body: Some(resp_body),
+                error: None,
+                request_headers: Some(format!(
+                    "Content-Type: application/json\nX-GitData-Event: {}\nX-GitData-Delivery: {}",
+                    task.event, task.id
+                )),
+                request_body: Some(
+                    String::from_utf8_lossy(&body_bytes).to_string(),
+                ),
+            }
+        }
+        Err(e) => WebhookDeliveryResult {
+            response_status: None,
+            response_headers: None,
+            response_body: None,
+            error: Some(e.to_string()),
+            request_headers: Some(format!(
+                "Content-Type: application/json\nX-GitData-Event: {}\nX-GitData-Delivery: {}",
+                task.event, task.id
+            )),
+            request_body: Some(
+                String::from_utf8_lossy(&body_bytes).to_string(),
+            ),
+        },
+    }
+}
+pub struct WebhookDeliveryResult {
+    pub request_headers: Option<String>,
+    pub request_body: Option<String>,
+    pub response_status: Option<i32>,
+    pub response_headers: Option<String>,
+    pub response_body: Option<String>,
+    pub error: Option<String>,
+}
diff --git a/lib/git/sync/worker.rs b/lib/git/sync/worker.rs
new file mode 100644
index 0000000..2eea2cc
--- /dev/null
+++ b/lib/git/sync/worker.rs
@@ -0,0 +1,496 @@
+use std::time::Duration;
+
+use cache::AppCache;
+use config::AppConfig;
+use db::{database::AppDatabase, sqlx};
+use deadpool_redis::cluster::Pool as RedisPool;
+use model::repos::RepoModel;
+use parsefile::TriggerEvent;
+
+use crate::sync::{
+    HookTask, TaskType,
+    cicheck::{CiCheckOutcome, check_and_enqueue},
+    consumer::SyncConsumer,
+    lock::{acquire_repo_lock, release_repo_lock},
+    webhook::{WebhookDeliveryTask, deliver_webhook},
+};
+pub struct SyncWorker {
+    pub consumer: SyncConsumer,
+    pub db: AppDatabase,
+    pub cache: AppCache,
+    pub redis_pool: RedisPool,
+    pub config: AppConfig,
+    pub max_retries: usize,
+    pub worker_id: String,
+}
+
+impl SyncWorker {
+    pub fn new(
+        consumer: SyncConsumer,
+        db: AppDatabase,
+        cache: AppCache,
+        redis_pool: RedisPool,
+        config: AppConfig,
+        worker_id: String,
+    ) -> Self {
+        Self {
+            consumer,
+            db,
+            cache,
+            redis_pool,
+            config,
+            max_retries: 3,
+            worker_id,
+        }
+    }
+    pub async fn run(&self) {
+        tracing::info!(worker_id = %self.worker_id, "sync worker starting");
+        let mut backoff_secs: u64 = 1;
+
+        loop {
+            let mut had_error = false;
+
+            for task_type in &[
+                TaskType::Sync,
+                TaskType::Fsck,
+                TaskType::Gc,
+                TaskType::Webhook,
+            ] {
+                let queue_key =
+                    self.consumer.queue_key_for_task_type(task_type);
+
+                if let Some((task_json, work_key)) =
+                    self.consumer.next(task_type).await
+                {
+                    let task: HookTask = match serde_json::from_str(&task_json)
+                    {
+                        Ok(t) => t,
+                        Err(e) => {
+                            tracing::error!(error = %e, "failed to deserialize hook task");
+                            self.consumer.ack(&task_json, &work_key).await;
+                            continue;
+                        }
+                    };
+
+                    tracing::info!(
+                        task_id = %task.id,
+                        repo_id = %task.repo_id,
+                        task_type = ?task.task_type,
+                        "processing hook task"
+                    );
+
+                    let result = self
+                        .process_task(&task, &task_json, &work_key, &queue_key)
+                        .await;
+
+                    match result {
+                        ProcessResult::Success => {
+                            self.consumer.ack(&task_json, &work_key).await;
+                            backoff_secs = 1;
+                        }
+                        ProcessResult::Locked => {
+                            self.consumer
+                                .nak_with_retry(
+                                    &task_json, &work_key, &queue_key,
+                                )
+                                .await;
+                            backoff_secs = 1;
+                        }
+                        ProcessResult::Error => {
+                            if task.retry_count >= self.max_retries {
+                                tracing::warn!(
+                                    task_id = %task.id,
+                                    repo_id = %task.repo_id,
+                                    retry_count = task.retry_count,
+                                    "max retries exceeded, dropping task"
+                                );
+                                self.consumer.ack(&task_json, &work_key).await;
+                            } else {
+                                tracing::warn!(
+                                    task_id = %task.id,
+                                    repo_id = %task.repo_id,
+                                    retry_count = task.retry_count,
+                                    "task failed, re-queueing"
+                                );
+                                let mut updated_task = task.clone();
+                                updated_task.retry_count += 1;
+                                if let Ok(updated_json) =
+                                    serde_json::to_string(&updated_task)
+                                {
+                                    self.consumer
+                                        .nak_with_retry(
+                                            &updated_json,
+                                            &work_key,
+                                            &queue_key,
+                                        )
+                                        .await;
+                                } else {
+                                    self.consumer
+                                        .nak_with_retry(
+                                            &task_json, &work_key, &queue_key,
+                                        )
+                                        .await;
+                                }
+                            }
+                            had_error = true;
+                        }
+                    }
+                }
+            }
+
+            if had_error {
+                tokio::time::sleep(Duration::from_secs(backoff_secs)).await;
+                backoff_secs = (backoff_secs * 2).min(32);
+            }
+        }
+    }
+
+    async fn process_task(
+        &self,
+        task: &HookTask,
+        _task_json: &str,
+        _work_key: &str,
+        _queue_key: &str,
+    ) -> ProcessResult {
+        match task.task_type {
+            TaskType::Sync => self.run_sync(task).await,
+            TaskType::Fsck => self.run_fsck(task).await,
+            TaskType::Gc => self.run_gc(task).await,
+            TaskType::Webhook => self.run_webhook(task).await,
+        }
+    }
+
+    async fn run_sync(&self, task: &HookTask) -> ProcessResult {
+        let repo_id = match task.repo_id.parse::<uuid::Uuid>() {
+            Ok(id) => id,
+            Err(e) => {
+                tracing::error!(error = %e, repo_id = %task.repo_id, "invalid repo_id UUID");
+                return ProcessResult::Error;
+            }
+        };
+
+        let lock_value = format!("{}:{}", self.worker_id, task.id);
+        let lock_result = acquire_repo_lock(
+            &self.redis_pool,
+            repo_id,
+            &lock_value,
+            300, // 5 min TTL
+        )
+        .await;
+
+        match lock_result {
+            Ok(true) => {}
+            Ok(false) => return ProcessResult::Locked,
+            Err(e) => {
+                tracing::error!(error = %e, repo_id = %repo_id, "failed to acquire repo lock");
+                return ProcessResult::Error;
+            }
+        }
+
+        let result = self.do_sync(repo_id).await;
+
+        release_repo_lock(&self.redis_pool, repo_id, &lock_value).await;
+
+        match result {
+            Ok(()) => ProcessResult::Success,
+            Err(e) => {
+                tracing::error!(error = %e, repo_id = %repo_id, "sync pipeline failed");
+                ProcessResult::Error
+            }
+        }
+    }
+
+    async fn do_sync(&self, repo_id: uuid::Uuid) -> anyhow::Result<()> {
+        let pool = self.db.reader();
+
+        let repo_model = sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at FROM repo WHERE id = $1"
+        )
+            .bind(repo_id)
+            .fetch_optional(pool)
+            .await?
+            .ok_or_else(|| anyhow::anyhow!("repo not found: {}", repo_id))?;
+
+        let bare_dir = std::path::PathBuf::from(&repo_model.storage_path);
+        if !bare_dir.exists() {
+            tracing::warn!(repo_id = %repo_id, "bare repo directory missing, skipping sync");
+            return Ok(());
+        }
+
+        let bare = crate::bare::GitBare { bare_dir };
+        if let Err(e) =
+            crate::sync::branch::sync_refs(&self.db, &bare, repo_id).await
+        {
+            tracing::error!(error = %e, repo_id = %repo_id, "sync_refs failed");
+        }
+
+        if let Err(e) =
+            crate::sync::commit::sync_commits(&self.db, &bare, repo_id).await
+        {
+            tracing::error!(error = %e, repo_id = %repo_id, "sync_commits failed");
+        }
+
+        if let Err(e) =
+            crate::sync::tag::sync_tags(&self.db, &bare, repo_id).await
+        {
+            tracing::error!(error = %e, repo_id = %repo_id, "sync_tags failed");
+        }
+
+        if let Err(e) =
+            crate::sync::lfs::sync_lfs_objects(&self.db, &bare, repo_id).await
+        {
+            tracing::error!(error = %e, repo_id = %repo_id, "sync_lfs_objects failed");
+        }
+
+        if let Err(e) =
+            crate::sync::language::sync_languages(&self.db, &bare, repo_id).await
+        {
+            tracing::error!(error = %e, repo_id = %repo_id, "sync_languages failed");
+        }
+
+        let gc_result = bare.git_command_trusted_unchecked(vec![
+            "gc".to_string(),
+            "--auto".to_string(),
+            "--quiet".to_string(),
+        ]);
+        if let Ok(output) = gc_result {
+            if !output.success {
+                tracing::warn!(repo_id = %repo_id, "git gc failed: {}", output.stderr_lossy());
+            }
+        }
+
+        let pattern = format!("git:rpc:cache:*:{}:*", repo_id);
+        let _ = self.cache.delete_pattern(&pattern).await;
+
+        tracing::info!(repo_id = %repo_id, "sync completed");
+        if let Err(e) = self
+            .run_ci_check(&repo_model.default_branch, &bare, repo_id)
+            .await
+        {
+            tracing::warn!(error = %e, repo_id = %repo_id, "CI check failed");
+        }
+
+        Ok(())
+    }
+
+    async fn run_fsck(&self, task: &HookTask) -> ProcessResult {
+        let repo_id = match task.repo_id.parse::<uuid::Uuid>() {
+            Ok(id) => id,
+            Err(_) => return ProcessResult::Error,
+        };
+
+        let pool = self.db.reader();
+
+        let storage_path = sqlx::query_scalar::<_, String>(
+            "SELECT storage_path FROM repo WHERE id = $1",
+        )
+        .bind(repo_id)
+        .fetch_optional(pool)
+        .await;
+
+        let storage_path = match storage_path {
+            Ok(Some(s)) => s,
+            _ => return ProcessResult::Error,
+        };
+
+        let bare = crate::bare::GitBare {
+            bare_dir: std::path::PathBuf::from(&storage_path),
+        };
+
+        let result = bare.git_command_trusted_unchecked(vec![
+            "fsck".to_string(),
+            "--full".to_string(),
+        ]);
+
+        match result {
+            Ok(output) if output.success => ProcessResult::Success,
+            Ok(output) => {
+                tracing::warn!(repo_id = %repo_id, "fsck failed: {}", output.stderr_lossy());
+                ProcessResult::Error
+            }
+            Err(e) => {
+                tracing::error!(error = %e, repo_id = %repo_id, "fsck command failed");
+                ProcessResult::Error
+            }
+        }
+    }
+
+    async fn run_gc(&self, task: &HookTask) -> ProcessResult {
+        let repo_id = match task.repo_id.parse::<uuid::Uuid>() {
+            Ok(id) => id,
+            Err(_) => return ProcessResult::Error,
+        };
+
+        let pool = self.db.reader();
+
+        let storage_path = sqlx::query_scalar::<_, String>(
+            "SELECT storage_path FROM repo WHERE id = $1",
+        )
+        .bind(repo_id)
+        .fetch_optional(pool)
+        .await;
+
+        let storage_path = match storage_path {
+            Ok(Some(s)) => s,
+            _ => return ProcessResult::Error,
+        };
+
+        let bare = crate::bare::GitBare {
+            bare_dir: std::path::PathBuf::from(&storage_path),
+        };
+
+        let result = bare
+            .git_command_trusted(vec!["gc".to_string(), "--auto".to_string()]);
+
+        match result {
+            Ok(_) => ProcessResult::Success,
+            Err(e) => {
+                tracing::error!(error = %e, repo_id = %repo_id, "gc command failed");
+                ProcessResult::Error
+            }
+        }
+    }
+
+    async fn run_ci_check(
+        &self,
+        default_branch: &str,
+        bare: &crate::bare::GitBare,
+        repo_id: uuid::Uuid,
+    ) -> anyhow::Result<()> {
+        let event = TriggerEvent::PushBranch(default_branch.to_owned());
+
+        let outcome =
+            check_and_enqueue(bare, repo_id, &event, &self.redis_pool).await?;
+
+        match outcome {
+            CiCheckOutcome::Enqueued => {
+                tracing::info!(
+                    repo_id = %repo_id,
+                    branch = %default_branch,
+                    "CI pipeline triggered"
+                );
+            }
+            CiCheckOutcome::NoPipelineFile => {
+                tracing::debug!(repo_id = %repo_id, "no pipeline.yaml found");
+            }
+            CiCheckOutcome::NotTriggered => {
+                tracing::debug!(
+                    repo_id = %repo_id,
+                    branch = %default_branch,
+                    "pipeline.yaml exists but not triggered for this event"
+                );
+            }
+        }
+
+        Ok(())
+    }
+    async fn run_webhook(&self, task: &HookTask) -> ProcessResult {
+        let repo_id = match task.repo_id.parse::<uuid::Uuid>() {
+            Ok(id) => id,
+            Err(_) => return ProcessResult::Error,
+        };
+
+        let event = task
+            .payload
+            .get("webhook_event")
+            .and_then(|v| v.as_str())
+            .unwrap_or("push");
+
+        let webhooks: Vec<(uuid::Uuid, String, Option<String>, String)> =
+            sqlx::query_as(
+                "SELECT id, url, secret_hash, events \
+             FROM repo_webhook WHERE repo = $1 AND active = true",
+            )
+            .bind(repo_id)
+            .fetch_all(self.db.reader())
+            .await
+            .unwrap_or_default();
+
+        for (wh_id, wh_url, wh_secret, wh_events) in webhooks {
+            let subscribed: Vec<&str> =
+                wh_events.split('.').filter(|s| !s.is_empty()).collect();
+            let matches = subscribed.iter().any(|e| {
+                *e == event
+                    || (*e == "push"
+                        && (event == "push_branch" || event == "push_tag"))
+            });
+            if !matches {
+                continue;
+            }
+
+            let delivery_id = uuid::Uuid::now_v7();
+            let now = chrono::Utc::now();
+
+            sqlx::query(
+                "INSERT INTO repo_webhook_delivery \
+                 (id, repo, webhook, event, request_headers, request_body, \
+                  response_status, response_headers, response_body, error, delivered_at, created_at) \
+                 VALUES ($1, $2, $3, $4, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $5)",
+            )
+            .bind(delivery_id)
+            .bind(repo_id)
+            .bind(wh_id)
+            .bind(event)
+            .bind(now)
+            .execute(self.db.writer())
+            .await
+            .ok();
+
+            let wh_task = WebhookDeliveryTask {
+                id: delivery_id.to_string(),
+                webhook_id: wh_id.to_string(),
+                repo_id: repo_id.to_string(),
+                event: event.to_string(),
+                url: wh_url,
+                secret: wh_secret,
+                payload: task.payload.clone(),
+                created_at: now,
+                retry_count: 0,
+            };
+
+            let result = deliver_webhook(&wh_task).await;
+
+            sqlx::query(
+                "UPDATE repo_webhook_delivery SET \
+                 request_headers = $1, request_body = $2, \
+                 response_status = $3, response_headers = $4, response_body = $5, \
+                 error = $6, delivered_at = $7 WHERE id = $8",
+            )
+            .bind(&result.request_headers)
+            .bind(&result.request_body)
+            .bind(result.response_status)
+            .bind(&result.response_headers)
+            .bind(&result.response_body)
+            .bind(&result.error)
+            .bind(now)
+            .bind(delivery_id)
+            .execute(self.db.writer())
+            .await
+            .ok();
+
+            if result.error.is_some() {
+                tracing::warn!(
+                    webhook_id = %wh_id,
+                    repo_id = %repo_id,
+                    error = ?result.error,
+                    "webhook delivery failed"
+                );
+            } else {
+                tracing::info!(
+                    webhook_id = %wh_id,
+                    repo_id = %repo_id,
+                    status = ?result.response_status,
+                    "webhook delivered"
+                );
+            }
+        }
+
+        ProcessResult::Success
+    }
+}
+
+enum ProcessResult {
+    Success,
+    Locked,
+    Error,
+}
diff --git a/lib/issues/Cargo.toml b/lib/issues/Cargo.toml
new file mode 100644
index 0000000..300fec1
--- /dev/null
+++ b/lib/issues/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "issues"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[dependencies]
+
+[lints]
+workspace = true
diff --git a/lib/issues/src/main.rs b/lib/issues/src/main.rs
new file mode 100644
index 0000000..e7a11a9
--- /dev/null
+++ b/lib/issues/src/main.rs
@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello, world!");
+}
diff --git a/lib/migrate/Cargo.toml b/lib/migrate/Cargo.toml
new file mode 100644
index 0000000..013a088
--- /dev/null
+++ b/lib/migrate/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "migrate"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[dependencies]
+tokio = { workspace = true, features = ["full"] }
+sqlx = { workspace = true, features = ["postgres", "runtime-tokio", "chrono", "uuid"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter"] }
+anyhow = { workspace = true }
+clap = { version = "4", features = ["derive"] }
+serde = { workspace = true, features = ["derive"] }
+
+[lints]
+workspace = true
\ No newline at end of file
diff --git a/lib/migrate/sql/agent/agent_compression_lock_down_01.sql b/lib/migrate/sql/agent/agent_compression_lock_down_01.sql
new file mode 100644
index 0000000..63e999a
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_compression_lock_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_compression_lock CASCADE;
diff --git a/lib/migrate/sql/agent/agent_compression_lock_up_01.sql b/lib/migrate/sql/agent/agent_compression_lock_up_01.sql
new file mode 100644
index 0000000..6831829
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_compression_lock_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS agent_compression_lock (
+    session_id UUID PRIMARY KEY REFERENCES agent_session(id) ON DELETE CASCADE,
+    holder TEXT NOT NULL,
+    acquired_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_compression_lock_expires
+    ON agent_compression_lock(expires_at);
diff --git a/lib/migrate/sql/agent/agent_conversation_compacted_summary_down_02.sql b/lib/migrate/sql/agent/agent_conversation_compacted_summary_down_02.sql
new file mode 100644
index 0000000..77ef7d0
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_conversation_compacted_summary_down_02.sql
@@ -0,0 +1 @@
+ALTER TABLE agent_conversation DROP COLUMN IF EXISTS compacted_summary;
diff --git a/lib/migrate/sql/agent/agent_conversation_compacted_summary_up_02.sql b/lib/migrate/sql/agent/agent_conversation_compacted_summary_up_02.sql
new file mode 100644
index 0000000..0f60054
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_conversation_compacted_summary_up_02.sql
@@ -0,0 +1 @@
+ALTER TABLE agent_conversation ADD COLUMN IF NOT EXISTS compacted_summary TEXT;
diff --git a/lib/migrate/sql/agent/agent_conversation_down_01.sql b/lib/migrate/sql/agent/agent_conversation_down_01.sql
new file mode 100644
index 0000000..aa4eadb
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_conversation_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_conversation CASCADE;
diff --git a/lib/migrate/sql/agent/agent_conversation_up_01.sql b/lib/migrate/sql/agent/agent_conversation_up_01.sql
new file mode 100644
index 0000000..67a34f2
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_conversation_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS agent_conversation (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session UUID NOT NULL,
+    title TEXT NOT NULL DEFAULT '',
+    created_by UUID NOT NULL,
+    last_message_at TIMESTAMPTZ,
+    archived_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/agent/agent_hook_registration_down_01.sql b/lib/migrate/sql/agent/agent_hook_registration_down_01.sql
new file mode 100644
index 0000000..04e031d
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_hook_registration_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_hook_registration CASCADE;
diff --git a/lib/migrate/sql/agent/agent_hook_registration_up_01.sql b/lib/migrate/sql/agent/agent_hook_registration_up_01.sql
new file mode 100644
index 0000000..ba49da2
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_hook_registration_up_01.sql
@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS agent_hook_registration (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id UUID NOT NULL REFERENCES agent_session(id) ON DELETE CASCADE,
+    hook_type TEXT NOT NULL,
+    handler_name TEXT NOT NULL,
+    config_json TEXT,
+    priority INTEGER NOT NULL DEFAULT 0,
+    enabled BOOLEAN NOT NULL DEFAULT true,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_hook_session
+    ON agent_hook_registration(session_id, hook_type);
diff --git a/lib/migrate/sql/agent/agent_knowledge_base_down_01.sql b/lib/migrate/sql/agent/agent_knowledge_base_down_01.sql
new file mode 100644
index 0000000..2523cae
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_knowledge_base_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_knowledge_base CASCADE;
diff --git a/lib/migrate/sql/agent/agent_knowledge_base_up_01.sql b/lib/migrate/sql/agent/agent_knowledge_base_up_01.sql
new file mode 100644
index 0000000..b618534
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_knowledge_base_up_01.sql
@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS agent_knowledge_base (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session UUID NOT NULL,
+    title TEXT NOT NULL,
+    source_type TEXT NOT NULL,
+    source_url TEXT,
+    content TEXT,
+    embedding_ref TEXT,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/agent/agent_long_term_memory_down_01.sql b/lib/migrate/sql/agent/agent_long_term_memory_down_01.sql
new file mode 100644
index 0000000..25a9fac
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_long_term_memory_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_long_term_memory CASCADE;
diff --git a/lib/migrate/sql/agent/agent_long_term_memory_session_key_down_02.sql b/lib/migrate/sql/agent/agent_long_term_memory_session_key_down_02.sql
new file mode 100644
index 0000000..1e60633
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_long_term_memory_session_key_down_02.sql
@@ -0,0 +1 @@
+DROP INDEX IF EXISTS idx_agent_ltm_session_key;
diff --git a/lib/migrate/sql/agent/agent_long_term_memory_session_key_up_02.sql b/lib/migrate/sql/agent/agent_long_term_memory_session_key_up_02.sql
new file mode 100644
index 0000000..31bab62
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_long_term_memory_session_key_up_02.sql
@@ -0,0 +1,4 @@
+-- Add partial unique index so we can upsert on (session, key) ignoring soft-deleted rows.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_ltm_session_key
+    ON agent_long_term_memory (session, key)
+    WHERE deleted_at IS NULL;
diff --git a/lib/migrate/sql/agent/agent_long_term_memory_up_01.sql b/lib/migrate/sql/agent/agent_long_term_memory_up_01.sql
new file mode 100644
index 0000000..dcd851f
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_long_term_memory_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS agent_long_term_memory (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session UUID NOT NULL,
+    key TEXT NOT NULL,
+    value TEXT NOT NULL,
+    importance INTEGER NOT NULL DEFAULT 0,
+    last_used_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/agent/agent_message_down_01.sql b/lib/migrate/sql/agent/agent_message_down_01.sql
new file mode 100644
index 0000000..7b3664b
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_message CASCADE;
diff --git a/lib/migrate/sql/agent/agent_message_down_03.sql b/lib/migrate/sql/agent/agent_message_down_03.sql
new file mode 100644
index 0000000..19031f9
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_down_03.sql
@@ -0,0 +1,6 @@
+DROP INDEX IF EXISTS idx_agent_message_search;
+
+ALTER TABLE agent_message
+    DROP COLUMN IF EXISTS search_vector,
+    DROP COLUMN IF EXISTS finish_reason,
+    DROP COLUMN IF EXISTS token_count;
diff --git a/lib/migrate/sql/agent/agent_message_fork_down_01.sql b/lib/migrate/sql/agent/agent_message_fork_down_01.sql
new file mode 100644
index 0000000..07d6dac
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_fork_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_message_fork CASCADE;
diff --git a/lib/migrate/sql/agent/agent_message_fork_up_01.sql b/lib/migrate/sql/agent/agent_message_fork_up_01.sql
new file mode 100644
index 0000000..4698605
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_fork_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS agent_message_fork (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_message UUID NOT NULL,
+    forked_conversation UUID NOT NULL,
+    forked_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/agent/agent_message_reasoning_content_down_02.sql b/lib/migrate/sql/agent/agent_message_reasoning_content_down_02.sql
new file mode 100644
index 0000000..078d788
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_reasoning_content_down_02.sql
@@ -0,0 +1,2 @@
+-- Remove reasoning_content column from agent_message table
+ALTER TABLE agent_message DROP COLUMN IF EXISTS reasoning_content;
diff --git a/lib/migrate/sql/agent/agent_message_reasoning_content_up_02.sql b/lib/migrate/sql/agent/agent_message_reasoning_content_up_02.sql
new file mode 100644
index 0000000..77ab6fd
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_reasoning_content_up_02.sql
@@ -0,0 +1,2 @@
+-- Add reasoning_content column to agent_message table
+ALTER TABLE agent_message ADD COLUMN IF NOT EXISTS reasoning_content TEXT;
diff --git a/lib/migrate/sql/agent/agent_message_up_01.sql b/lib/migrate/sql/agent/agent_message_up_01.sql
new file mode 100644
index 0000000..08b6ad2
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS agent_message (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    conversation UUID NOT NULL,
+    parent UUID,
+    role TEXT NOT NULL,
+    author UUID,
+    content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'text',
+    status TEXT NOT NULL DEFAULT 'sent',
+    model_invocation UUID,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/agent/agent_message_up_03.sql b/lib/migrate/sql/agent/agent_message_up_03.sql
new file mode 100644
index 0000000..f4ae49e
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_message_up_03.sql
@@ -0,0 +1,10 @@
+ALTER TABLE agent_message
+    ADD COLUMN IF NOT EXISTS token_count INTEGER,
+    ADD COLUMN IF NOT EXISTS finish_reason TEXT;
+
+ALTER TABLE agent_message
+    ADD COLUMN IF NOT EXISTS search_vector tsvector
+        GENERATED ALWAYS AS (to_tsvector('english', coalesce(content, ''))) STORED;
+
+CREATE INDEX IF NOT EXISTS idx_agent_message_search
+    ON agent_message USING GIN (search_vector);
diff --git a/lib/migrate/sql/agent/agent_model_invocation_down_01.sql b/lib/migrate/sql/agent/agent_model_invocation_down_01.sql
new file mode 100644
index 0000000..7374c19
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_model_invocation_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_model_invocation CASCADE;
diff --git a/lib/migrate/sql/agent/agent_model_invocation_up_01.sql b/lib/migrate/sql/agent/agent_model_invocation_up_01.sql
new file mode 100644
index 0000000..b58ec47
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_model_invocation_up_01.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS agent_model_invocation (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session UUID NOT NULL,
+    conversation UUID,
+    message UUID,
+    model_version UUID NOT NULL,
+    request_id TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    prompt TEXT,
+    response TEXT,
+    error TEXT,
+    started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    finished_at TIMESTAMPTZ,
+    latency_ms BIGINT
+);
diff --git a/lib/migrate/sql/agent/agent_session_config_down_02.sql b/lib/migrate/sql/agent/agent_session_config_down_02.sql
new file mode 100644
index 0000000..c4b8315
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_session_config_down_02.sql
@@ -0,0 +1,8 @@
+ALTER TABLE agent_session
+    DROP COLUMN IF EXISTS rollback_from_version,
+    DROP COLUMN IF EXISTS published_at,
+    DROP COLUMN IF EXISTS version,
+    DROP COLUMN IF EXISTS visibility,
+    DROP COLUMN IF EXISTS variables,
+    DROP COLUMN IF EXISTS knowledge_base_ids,
+    DROP COLUMN IF EXISTS tool_policy;
diff --git a/lib/migrate/sql/agent/agent_session_config_up_02.sql b/lib/migrate/sql/agent/agent_session_config_up_02.sql
new file mode 100644
index 0000000..30fe96e
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_session_config_up_02.sql
@@ -0,0 +1,8 @@
+ALTER TABLE agent_session
+    ADD COLUMN IF NOT EXISTS tool_policy TEXT,
+    ADD COLUMN IF NOT EXISTS knowledge_base_ids TEXT,
+    ADD COLUMN IF NOT EXISTS variables TEXT,
+    ADD COLUMN IF NOT EXISTS visibility TEXT NOT NULL DEFAULT 'private',
+    ADD COLUMN IF NOT EXISTS version INTEGER NOT NULL DEFAULT 1,
+    ADD COLUMN IF NOT EXISTS published_at TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS rollback_from_version INTEGER;
diff --git a/lib/migrate/sql/agent/agent_session_down_01.sql b/lib/migrate/sql/agent/agent_session_down_01.sql
new file mode 100644
index 0000000..4bca45f
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_session_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_session CASCADE;
diff --git a/lib/migrate/sql/agent/agent_session_down_03.sql b/lib/migrate/sql/agent/agent_session_down_03.sql
new file mode 100644
index 0000000..9fc5da4
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_session_down_03.sql
@@ -0,0 +1,7 @@
+ALTER TABLE agent_session
+    DROP COLUMN IF EXISTS source,
+    DROP COLUMN IF EXISTS parent_session_id,
+    DROP COLUMN IF EXISTS toolset_json,
+    DROP COLUMN IF EXISTS memory_provider,
+    DROP COLUMN IF EXISTS memory_provider_config,
+    DROP COLUMN IF EXISTS iteration_budget;
diff --git a/lib/migrate/sql/agent/agent_session_up_01.sql b/lib/migrate/sql/agent/agent_session_up_01.sql
new file mode 100644
index 0000000..a5100ec
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_session_up_01.sql
@@ -0,0 +1,24 @@
+CREATE TABLE IF NOT EXISTS agent_session (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    "user" UUID,
+    wk UUID,
+    name TEXT NOT NULL,
+    description TEXT,
+    agent_kind TEXT NOT NULL,
+    model_version UUID,
+    system_prompt TEXT,
+    temperature REAL,
+    max_output_tokens INTEGER,
+    tool_policy TEXT,
+    knowledge_base_ids TEXT,
+    variables TEXT,
+    visibility TEXT NOT NULL DEFAULT 'private',
+    version INTEGER NOT NULL DEFAULT 1,
+    published_at TIMESTAMPTZ,
+    rollback_from_version INTEGER,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/agent/agent_session_up_03.sql b/lib/migrate/sql/agent/agent_session_up_03.sql
new file mode 100644
index 0000000..ddf7d76
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_session_up_03.sql
@@ -0,0 +1,8 @@
+-- depends_on:agent_conversation
+ALTER TABLE agent_session
+    ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT 'api',
+    ADD COLUMN IF NOT EXISTS parent_session_id UUID REFERENCES agent_session(id),
+    ADD COLUMN IF NOT EXISTS toolset_json TEXT,
+    ADD COLUMN IF NOT EXISTS memory_provider TEXT,
+    ADD COLUMN IF NOT EXISTS memory_provider_config TEXT,
+    ADD COLUMN IF NOT EXISTS iteration_budget INTEGER NOT NULL DEFAULT 90;
diff --git a/lib/migrate/sql/agent/agent_subagent_session_down_01.sql b/lib/migrate/sql/agent/agent_subagent_session_down_01.sql
new file mode 100644
index 0000000..78dd522
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_subagent_session_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_subagent_session CASCADE;
diff --git a/lib/migrate/sql/agent/agent_subagent_session_up_01.sql b/lib/migrate/sql/agent/agent_subagent_session_up_01.sql
new file mode 100644
index 0000000..f390044
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_subagent_session_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS agent_subagent_session (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_session UUID NOT NULL,
+    child_session UUID NOT NULL,
+    name TEXT NOT NULL,
+    purpose TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    ended_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/agent/agent_token_usage_down_01.sql b/lib/migrate/sql/agent/agent_token_usage_down_01.sql
new file mode 100644
index 0000000..30ade9c
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_token_usage_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_token_usage CASCADE;
diff --git a/lib/migrate/sql/agent/agent_token_usage_down_02.sql b/lib/migrate/sql/agent/agent_token_usage_down_02.sql
new file mode 100644
index 0000000..04967cd
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_token_usage_down_02.sql
@@ -0,0 +1,4 @@
+ALTER TABLE agent_token_usage
+    DROP COLUMN IF EXISTS reasoning_tokens,
+    DROP COLUMN IF EXISTS cache_write_tokens,
+    DROP COLUMN IF EXISTS cache_read_tokens;
diff --git a/lib/migrate/sql/agent/agent_token_usage_up_01.sql b/lib/migrate/sql/agent/agent_token_usage_up_01.sql
new file mode 100644
index 0000000..5d24f02
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_token_usage_up_01.sql
@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS agent_token_usage (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    invocation UUID NOT NULL,
+    session UUID NOT NULL,
+    model_version UUID NOT NULL,
+    input_tokens BIGINT NOT NULL DEFAULT 0,
+    output_tokens BIGINT NOT NULL DEFAULT 0,
+    cached_input_tokens BIGINT NOT NULL DEFAULT 0,
+    total_tokens BIGINT NOT NULL DEFAULT 0,
+    cost NUMERIC,
+    currency TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/agent/agent_token_usage_up_02.sql b/lib/migrate/sql/agent/agent_token_usage_up_02.sql
new file mode 100644
index 0000000..46d14e8
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_token_usage_up_02.sql
@@ -0,0 +1,4 @@
+ALTER TABLE agent_token_usage
+    ADD COLUMN IF NOT EXISTS cache_read_tokens BIGINT NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS cache_write_tokens BIGINT NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS reasoning_tokens BIGINT NOT NULL DEFAULT 0;
diff --git a/lib/migrate/sql/agent/agent_tool_call_log_down_01.sql b/lib/migrate/sql/agent/agent_tool_call_log_down_01.sql
new file mode 100644
index 0000000..269dd62
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_tool_call_log_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_tool_call_log CASCADE;
diff --git a/lib/migrate/sql/agent/agent_tool_call_log_tool_id_down_02.sql b/lib/migrate/sql/agent/agent_tool_call_log_tool_id_down_02.sql
new file mode 100644
index 0000000..9b678a0
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_tool_call_log_tool_id_down_02.sql
@@ -0,0 +1,2 @@
+ALTER TABLE agent_tool_call_log
+    DROP COLUMN IF EXISTS tool_call_id;
diff --git a/lib/migrate/sql/agent/agent_tool_call_log_tool_id_up_02.sql b/lib/migrate/sql/agent/agent_tool_call_log_tool_id_up_02.sql
new file mode 100644
index 0000000..264f2bc
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_tool_call_log_tool_id_up_02.sql
@@ -0,0 +1,2 @@
+ALTER TABLE agent_tool_call_log
+    ADD COLUMN IF NOT EXISTS tool_call_id TEXT;
diff --git a/lib/migrate/sql/agent/agent_tool_call_log_up_01.sql b/lib/migrate/sql/agent/agent_tool_call_log_up_01.sql
new file mode 100644
index 0000000..a285d93
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_tool_call_log_up_01.sql
@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS agent_tool_call_log (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    invocation UUID,
+    session UUID NOT NULL,
+    conversation UUID,
+    message UUID,
+    tool_call_id TEXT,
+    tool_name TEXT NOT NULL,
+    arguments TEXT,
+    result TEXT,
+    error TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    finished_at TIMESTAMPTZ,
+    latency_ms BIGINT
+);
diff --git a/lib/migrate/sql/agent/agent_trace_down_01.sql b/lib/migrate/sql/agent/agent_trace_down_01.sql
new file mode 100644
index 0000000..831b700
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_trace_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS agent_trace CASCADE;
diff --git a/lib/migrate/sql/agent/agent_trace_up_01.sql b/lib/migrate/sql/agent/agent_trace_up_01.sql
new file mode 100644
index 0000000..99d2e45
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_trace_up_01.sql
@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS agent_trace (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    invocation UUID NOT NULL REFERENCES agent_model_invocation(id),
+    conversation UUID NOT NULL,
+    sequence INT NOT NULL,
+    phase TEXT NOT NULL CHECK (phase IN ('think', 'answer', 'act', 'summarize')),
+    content TEXT,
+    tool_calls JSONB,
+    tool_results JSONB,
+    input_tokens BIGINT,
+    output_tokens BIGINT,
+    metadata JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_trace_invocation ON agent_trace(invocation);
+CREATE INDEX IF NOT EXISTS idx_agent_trace_conversation ON agent_trace(conversation, sequence);
diff --git a/lib/migrate/sql/agent/agent_z_model_invocations_compat_down_01.sql b/lib/migrate/sql/agent/agent_z_model_invocations_compat_down_01.sql
new file mode 100644
index 0000000..4b42353
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_z_model_invocations_compat_down_01.sql
@@ -0,0 +1,9 @@
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM pg_class
+        WHERE oid = to_regclass('agent_model_invocations') AND relkind = 'v'
+    ) THEN
+        DROP VIEW agent_model_invocations;
+    END IF;
+END $$;
diff --git a/lib/migrate/sql/agent/agent_z_model_invocations_compat_up_01.sql b/lib/migrate/sql/agent/agent_z_model_invocations_compat_up_01.sql
new file mode 100644
index 0000000..9af20df
--- /dev/null
+++ b/lib/migrate/sql/agent/agent_z_model_invocations_compat_up_01.sql
@@ -0,0 +1,21 @@
+DO $$
+BEGIN
+    IF to_regclass('agent_model_invocations') IS NULL THEN
+        CREATE VIEW agent_model_invocations AS
+        SELECT
+            id,
+            session,
+            conversation,
+            message,
+            model_version,
+            request_id,
+            status,
+            prompt,
+            response,
+            error,
+            started_at,
+            finished_at,
+            latency_ms
+        FROM agent_model_invocation;
+    END IF;
+END $$;
diff --git a/lib/migrate/sql/ai/ai_model_card_down_01.sql b/lib/migrate/sql/ai/ai_model_card_down_01.sql
new file mode 100644
index 0000000..4763729
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_card_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_model_card CASCADE;
diff --git a/lib/migrate/sql/ai/ai_model_card_up_01.sql b/lib/migrate/sql/ai/ai_model_card_up_01.sql
new file mode 100644
index 0000000..cd1d4ec
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_card_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS ai_model_card (
+    model UUID PRIMARY KEY,
+    overview TEXT,
+    strengths TEXT,
+    limitations TEXT,
+    safety_notes TEXT,
+    eval_summary TEXT,
+    metadata TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/ai/ai_model_discussion_down_01.sql b/lib/migrate/sql/ai/ai_model_discussion_down_01.sql
new file mode 100644
index 0000000..254d7ac
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_discussion_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_model_discussion CASCADE;
diff --git a/lib/migrate/sql/ai/ai_model_discussion_up_01.sql b/lib/migrate/sql/ai/ai_model_discussion_up_01.sql
new file mode 100644
index 0000000..16956b1
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_discussion_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS ai_model_discussion (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    model UUID NOT NULL,
+    "user" UUID NOT NULL,
+    parent UUID,
+    body TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/ai/ai_model_down_01.sql b/lib/migrate/sql/ai/ai_model_down_01.sql
new file mode 100644
index 0000000..ccf5a13
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_model CASCADE;
diff --git a/lib/migrate/sql/ai/ai_model_like_down_01.sql b/lib/migrate/sql/ai/ai_model_like_down_01.sql
new file mode 100644
index 0000000..2bbec5d
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_like_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_model_like CASCADE;
diff --git a/lib/migrate/sql/ai/ai_model_like_up_01.sql b/lib/migrate/sql/ai/ai_model_like_up_01.sql
new file mode 100644
index 0000000..fd626ca
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_like_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS ai_model_like (
+    model UUID NOT NULL,
+    "user" UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (model, "user")
+);
diff --git a/lib/migrate/sql/ai/ai_model_model_tag_down_01.sql b/lib/migrate/sql/ai/ai_model_model_tag_down_01.sql
new file mode 100644
index 0000000..583b04a
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_model_tag_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_model_model_tag CASCADE;
diff --git a/lib/migrate/sql/ai/ai_model_model_tag_up_01.sql b/lib/migrate/sql/ai/ai_model_model_tag_up_01.sql
new file mode 100644
index 0000000..1ab23fa
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_model_tag_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS ai_model_model_tag (
+    model UUID NOT NULL,
+    tag TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (model, tag)
+);
diff --git a/lib/migrate/sql/ai/ai_model_up_01.sql b/lib/migrate/sql/ai/ai_model_up_01.sql
new file mode 100644
index 0000000..a23c766
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_up_01.sql
@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS ai_model (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    provider UUID NOT NULL,
+    name TEXT NOT NULL,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    modality TEXT NOT NULL,
+    context_window INTEGER,
+    input_token_limit INTEGER,
+    output_token_limit INTEGER,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    public BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/ai/ai_model_version_down_01.sql b/lib/migrate/sql/ai/ai_model_version_down_01.sql
new file mode 100644
index 0000000..033ebef
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_version_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_model_version CASCADE;
diff --git a/lib/migrate/sql/ai/ai_model_version_up_01.sql b/lib/migrate/sql/ai/ai_model_version_up_01.sql
new file mode 100644
index 0000000..cb839ca
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_model_version_up_01.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS ai_model_version (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    model UUID NOT NULL,
+    version TEXT NOT NULL,
+    provider_model_name TEXT NOT NULL,
+    input_price_per_million NUMERIC,
+    output_price_per_million NUMERIC,
+    cached_input_price_per_million NUMERIC,
+    training_cutoff TEXT,
+    released_at TIMESTAMPTZ,
+    deprecated_at TIMESTAMPTZ,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/ai/ai_provider_down_01.sql b/lib/migrate/sql/ai/ai_provider_down_01.sql
new file mode 100644
index 0000000..ed37ba4
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_provider_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ai_provider CASCADE;
diff --git a/lib/migrate/sql/ai/ai_provider_up_01.sql b/lib/migrate/sql/ai/ai_provider_up_01.sql
new file mode 100644
index 0000000..32e69c5
--- /dev/null
+++ b/lib/migrate/sql/ai/ai_provider_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS ai_provider (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    base_url TEXT,
+    website_url TEXT,
+    logo_url TEXT,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/issue/issue_assignee_down_01.sql b/lib/migrate/sql/issue/issue_assignee_down_01.sql
new file mode 100644
index 0000000..3df6a6b
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_assignee_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_assignee CASCADE;
diff --git a/lib/migrate/sql/issue/issue_assignee_up_01.sql b/lib/migrate/sql/issue/issue_assignee_up_01.sql
new file mode 100644
index 0000000..b19739a
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_assignee_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS issue_assignee (
+    issue UUID NOT NULL REFERENCES issue(id),
+    "user" UUID NOT NULL,
+    assigned_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (issue, "user")
+);
diff --git a/lib/migrate/sql/issue/issue_comment_down_01.sql b/lib/migrate/sql/issue/issue_comment_down_01.sql
new file mode 100644
index 0000000..b889eb4
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_comment_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_comment CASCADE;
diff --git a/lib/migrate/sql/issue/issue_comment_up_01.sql b/lib/migrate/sql/issue/issue_comment_up_01.sql
new file mode 100644
index 0000000..c5e28d4
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_comment_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS issue_comment (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    issue UUID NOT NULL REFERENCES issue(id),
+    author UUID NOT NULL,
+    body TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/issue/issue_down_01.sql b/lib/migrate/sql/issue/issue_down_01.sql
new file mode 100644
index 0000000..896d131
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue CASCADE;
diff --git a/lib/migrate/sql/issue/issue_event_down_01.sql b/lib/migrate/sql/issue/issue_event_down_01.sql
new file mode 100644
index 0000000..e90988c
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_event_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_event CASCADE;
diff --git a/lib/migrate/sql/issue/issue_event_up_01.sql b/lib/migrate/sql/issue/issue_event_up_01.sql
new file mode 100644
index 0000000..256a033
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_event_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS issue_event (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    issue UUID NOT NULL REFERENCES issue(id),
+    actor UUID,
+    event TEXT NOT NULL,
+    from_value TEXT,
+    to_value TEXT,
+    metadata TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/issue/issue_label_down_01.sql b/lib/migrate/sql/issue/issue_label_down_01.sql
new file mode 100644
index 0000000..f39be4d
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_label_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_label CASCADE;
diff --git a/lib/migrate/sql/issue/issue_label_up_01.sql b/lib/migrate/sql/issue/issue_label_up_01.sql
new file mode 100644
index 0000000..761cc37
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_label_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS issue_label (
+    issue UUID NOT NULL REFERENCES issue(id),
+    label UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (issue, label)
+);
diff --git a/lib/migrate/sql/issue/issue_milestone_down_01.sql b/lib/migrate/sql/issue/issue_milestone_down_01.sql
new file mode 100644
index 0000000..b8104ad
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_milestone_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_milestone CASCADE;
diff --git a/lib/migrate/sql/issue/issue_milestone_up_01.sql b/lib/migrate/sql/issue/issue_milestone_up_01.sql
new file mode 100644
index 0000000..318f778
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_milestone_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS issue_milestone (
+    issue UUID NOT NULL REFERENCES issue(id),
+    milestone UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (issue, milestone)
+);
diff --git a/lib/migrate/sql/issue/issue_pull_request_down_01.sql b/lib/migrate/sql/issue/issue_pull_request_down_01.sql
new file mode 100644
index 0000000..447ebf9
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_pull_request_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_pull_request CASCADE;
diff --git a/lib/migrate/sql/issue/issue_pull_request_up_01.sql b/lib/migrate/sql/issue/issue_pull_request_up_01.sql
new file mode 100644
index 0000000..a64f9b6
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_pull_request_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS issue_pull_request (
+    issue UUID NOT NULL REFERENCES issue(id),
+    pull_request UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (issue, pull_request)
+);
diff --git a/lib/migrate/sql/issue/issue_reaction_down_01.sql b/lib/migrate/sql/issue/issue_reaction_down_01.sql
new file mode 100644
index 0000000..58957ab
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_reaction_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_reaction CASCADE;
diff --git a/lib/migrate/sql/issue/issue_reaction_up_01.sql b/lib/migrate/sql/issue/issue_reaction_up_01.sql
new file mode 100644
index 0000000..b239cef
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_reaction_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS issue_reaction (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    issue UUID NOT NULL REFERENCES issue(id),
+    comment UUID REFERENCES issue_comment(id),
+    "user" UUID NOT NULL,
+    reaction TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/issue/issue_reference_down_01.sql b/lib/migrate/sql/issue/issue_reference_down_01.sql
new file mode 100644
index 0000000..c70af9b
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_reference_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_reference CASCADE;
diff --git a/lib/migrate/sql/issue/issue_reference_up_01.sql b/lib/migrate/sql/issue/issue_reference_up_01.sql
new file mode 100644
index 0000000..6687f5f
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_reference_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS issue_reference (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    issue UUID NOT NULL REFERENCES issue(id),
+    target_type TEXT NOT NULL,
+    target_id UUID NOT NULL,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/issue/issue_repo_down_01.sql b/lib/migrate/sql/issue/issue_repo_down_01.sql
new file mode 100644
index 0000000..793e8e0
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_repo_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS issue_repo CASCADE;
diff --git a/lib/migrate/sql/issue/issue_repo_up_01.sql b/lib/migrate/sql/issue/issue_repo_up_01.sql
new file mode 100644
index 0000000..cf0355c
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_repo_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS issue_repo (
+    issue UUID NOT NULL REFERENCES issue(id),
+    repo UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (issue, repo)
+);
diff --git a/lib/migrate/sql/issue/issue_up_01.sql b/lib/migrate/sql/issue/issue_up_01.sql
new file mode 100644
index 0000000..002af55
--- /dev/null
+++ b/lib/migrate/sql/issue/issue_up_01.sql
@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS issue (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    number BIGINT NOT NULL,
+    title TEXT NOT NULL,
+    body TEXT,
+    state TEXT NOT NULL DEFAULT 'open',
+    priority TEXT NOT NULL DEFAULT 'medium',
+    author UUID NOT NULL,
+    closed_by UUID,
+    closed_at TIMESTAMPTZ,
+    due_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/issue/label_down_01.sql b/lib/migrate/sql/issue/label_down_01.sql
new file mode 100644
index 0000000..ace0845
--- /dev/null
+++ b/lib/migrate/sql/issue/label_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS label CASCADE;
diff --git a/lib/migrate/sql/issue/label_up_01.sql b/lib/migrate/sql/issue/label_up_01.sql
new file mode 100644
index 0000000..17ecb13
--- /dev/null
+++ b/lib/migrate/sql/issue/label_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS label (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    name TEXT NOT NULL,
+    color TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/issue/milestone_down_01.sql b/lib/migrate/sql/issue/milestone_down_01.sql
new file mode 100644
index 0000000..ba8a87a
--- /dev/null
+++ b/lib/migrate/sql/issue/milestone_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS milestone CASCADE;
diff --git a/lib/migrate/sql/issue/milestone_up_01.sql b/lib/migrate/sql/issue/milestone_up_01.sql
new file mode 100644
index 0000000..62f76c7
--- /dev/null
+++ b/lib/migrate/sql/issue/milestone_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS milestone (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT,
+    state TEXT NOT NULL DEFAULT 'open',
+    due_at TIMESTAMPTZ,
+    closed_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/notify/user_app_notify_down_01.sql b/lib/migrate/sql/notify/user_app_notify_down_01.sql
new file mode 100644
index 0000000..dc2891c
--- /dev/null
+++ b/lib/migrate/sql/notify/user_app_notify_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_app_notify CASCADE;
diff --git a/lib/migrate/sql/notify/user_app_notify_up_01.sql b/lib/migrate/sql/notify/user_app_notify_up_01.sql
new file mode 100644
index 0000000..e85c49b
--- /dev/null
+++ b/lib/migrate/sql/notify/user_app_notify_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS user_app_notify (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    "user" UUID NOT NULL,
+    title TEXT NOT NULL,
+    body TEXT NOT NULL,
+    notify_type TEXT NOT NULL,
+    target_type TEXT,
+    target_id UUID,
+    metadata TEXT,
+    read_at TIMESTAMPTZ,
+    archived_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/notify/user_email_notify_down_01.sql b/lib/migrate/sql/notify/user_email_notify_down_01.sql
new file mode 100644
index 0000000..69fc324
--- /dev/null
+++ b/lib/migrate/sql/notify/user_email_notify_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_email_notify CASCADE;
diff --git a/lib/migrate/sql/notify/user_email_notify_up_01.sql b/lib/migrate/sql/notify/user_email_notify_up_01.sql
new file mode 100644
index 0000000..f730b08
--- /dev/null
+++ b/lib/migrate/sql/notify/user_email_notify_up_01.sql
@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS user_email_notify (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    "user" UUID NOT NULL,
+    email TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    template TEXT NOT NULL,
+    body_text TEXT,
+    body_html TEXT,
+    notify_type TEXT NOT NULL,
+    target_type TEXT,
+    target_id UUID,
+    metadata TEXT,
+    status TEXT NOT NULL DEFAULT 'queued',
+    provider_message_id TEXT,
+    error TEXT,
+    retry_count INTEGER NOT NULL DEFAULT 0,
+    queued_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    sent_at TIMESTAMPTZ,
+    delivered_at TIMESTAMPTZ,
+    opened_at TIMESTAMPTZ,
+    clicked_at TIMESTAMPTZ,
+    failed_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_assignee_down_01.sql b/lib/migrate/sql/pull_request/pull_request_assignee_down_01.sql
new file mode 100644
index 0000000..30878ae
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_assignee_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_assignee CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_assignee_up_01.sql b/lib/migrate/sql/pull_request/pull_request_assignee_up_01.sql
new file mode 100644
index 0000000..2bb9031
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_assignee_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS pull_request_assignee (
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    "user" UUID NOT NULL,
+    assigned_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (pull_request, "user")
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_comment_down_01.sql b/lib/migrate/sql/pull_request/pull_request_comment_down_01.sql
new file mode 100644
index 0000000..4e7a986
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_comment_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_comment CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_comment_up_01.sql b/lib/migrate/sql/pull_request/pull_request_comment_up_01.sql
new file mode 100644
index 0000000..aca9d29
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_comment_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS pull_request_comment (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    author UUID NOT NULL,
+    body TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_commit_down_01.sql b/lib/migrate/sql/pull_request/pull_request_commit_down_01.sql
new file mode 100644
index 0000000..ac4901c
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_commit_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_commit CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_commit_up_01.sql b/lib/migrate/sql/pull_request/pull_request_commit_up_01.sql
new file mode 100644
index 0000000..b97815e
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_commit_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS pull_request_commit (
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    commit UUID NOT NULL,
+    sha TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (pull_request, commit)
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_down_01.sql b/lib/migrate/sql/pull_request/pull_request_down_01.sql
new file mode 100644
index 0000000..8eff68d
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_label_down_01.sql b/lib/migrate/sql/pull_request/pull_request_label_down_01.sql
new file mode 100644
index 0000000..70a7794
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_label_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_label CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_label_up_01.sql b/lib/migrate/sql/pull_request/pull_request_label_up_01.sql
new file mode 100644
index 0000000..80f8873
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_label_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS pull_request_label (
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    label UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (pull_request, label)
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_reaction_down_01.sql b/lib/migrate/sql/pull_request/pull_request_reaction_down_01.sql
new file mode 100644
index 0000000..5c1a290
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_reaction_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_reaction CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_reaction_up_01.sql b/lib/migrate/sql/pull_request/pull_request_reaction_up_01.sql
new file mode 100644
index 0000000..302e586
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_reaction_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS pull_request_reaction (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    comment UUID REFERENCES pull_request_comment(id),
+    "user" UUID NOT NULL,
+    reaction TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_review_comment_down_01.sql b/lib/migrate/sql/pull_request/pull_request_review_comment_down_01.sql
new file mode 100644
index 0000000..2aba044
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_comment_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_review_comment CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_review_comment_up_01.sql b/lib/migrate/sql/pull_request/pull_request_review_comment_up_01.sql
new file mode 100644
index 0000000..e9c9e37
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_comment_up_01.sql
@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS pull_request_review_comment (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    review UUID REFERENCES pull_request_review(id),
+    author UUID NOT NULL,
+    body TEXT NOT NULL,
+    path TEXT NOT NULL,
+    commit_sha TEXT NOT NULL,
+    original_commit_sha TEXT,
+    line INTEGER,
+    original_line INTEGER,
+    side TEXT,
+    resolved BOOLEAN NOT NULL DEFAULT FALSE,
+    resolved_by UUID,
+    resolved_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_review_down_01.sql b/lib/migrate/sql/pull_request/pull_request_review_down_01.sql
new file mode 100644
index 0000000..75be7f4
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_review CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_review_reaction_down_01.sql b/lib/migrate/sql/pull_request/pull_request_review_reaction_down_01.sql
new file mode 100644
index 0000000..7b7afde
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_reaction_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_review_reaction CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_review_reaction_up_01.sql b/lib/migrate/sql/pull_request/pull_request_review_reaction_up_01.sql
new file mode 100644
index 0000000..55fa418
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_reaction_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS pull_request_review_reaction (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    review_comment UUID NOT NULL REFERENCES pull_request_review_comment(id),
+    "user" UUID NOT NULL,
+    reaction TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_review_request_down_01.sql b/lib/migrate/sql/pull_request/pull_request_review_request_down_01.sql
new file mode 100644
index 0000000..64d9f3c
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_request_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS pull_request_review_request CASCADE;
diff --git a/lib/migrate/sql/pull_request/pull_request_review_request_up_01.sql b/lib/migrate/sql/pull_request/pull_request_review_request_up_01.sql
new file mode 100644
index 0000000..f2d4a3b
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_request_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS pull_request_review_request (
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    reviewer UUID,
+    "group" UUID,
+    requested_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    removed_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_review_up_01.sql b/lib/migrate/sql/pull_request/pull_request_review_up_01.sql
new file mode 100644
index 0000000..ed143f9
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_review_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS pull_request_review (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pull_request UUID NOT NULL REFERENCES pull_request(id),
+    reviewer UUID NOT NULL,
+    state TEXT NOT NULL,
+    body TEXT,
+    commit_sha TEXT,
+    submitted_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    dismissed_by UUID,
+    dismissed_at TIMESTAMPTZ,
+    dismiss_reason TEXT
+);
diff --git a/lib/migrate/sql/pull_request/pull_request_up_01.sql b/lib/migrate/sql/pull_request/pull_request_up_01.sql
new file mode 100644
index 0000000..f1a0379
--- /dev/null
+++ b/lib/migrate/sql/pull_request/pull_request_up_01.sql
@@ -0,0 +1,22 @@
+CREATE TABLE IF NOT EXISTS pull_request (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL,
+    number BIGINT NOT NULL,
+    title TEXT NOT NULL,
+    body TEXT,
+    state TEXT NOT NULL DEFAULT 'open',
+    draft BOOLEAN NOT NULL DEFAULT FALSE,
+    author UUID NOT NULL,
+    source_repo UUID NOT NULL,
+    source_branch TEXT NOT NULL,
+    source_sha TEXT NOT NULL,
+    target_branch TEXT NOT NULL,
+    target_sha TEXT NOT NULL,
+    merged_by UUID,
+    merged_at TIMESTAMPTZ,
+    closed_by UUID,
+    closed_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/repo/repo_audit_log_down_01.sql b/lib/migrate/sql/repo/repo_audit_log_down_01.sql
new file mode 100644
index 0000000..97324f5
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_audit_log_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_audit_log CASCADE;
diff --git a/lib/migrate/sql/repo/repo_audit_log_up_01.sql b/lib/migrate/sql/repo/repo_audit_log_up_01.sql
new file mode 100644
index 0000000..7a5f269
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_audit_log_up_01.sql
@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS repo_audit_log (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    actor UUID,
+    action TEXT NOT NULL,
+    target_type TEXT NOT NULL,
+    target_id TEXT,
+    ip_address TEXT,
+    user_agent TEXT,
+    metadata TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_commit_down_01.sql b/lib/migrate/sql/repo/repo_commit_down_01.sql
new file mode 100644
index 0000000..f5c284d
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_commit_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_commit CASCADE;
diff --git a/lib/migrate/sql/repo/repo_commit_status_down_01.sql b/lib/migrate/sql/repo/repo_commit_status_down_01.sql
new file mode 100644
index 0000000..5330ecf
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_commit_status_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_commit_status;
\ No newline at end of file
diff --git a/lib/migrate/sql/repo/repo_commit_status_up_01.sql b/lib/migrate/sql/repo/repo_commit_status_up_01.sql
new file mode 100644
index 0000000..57ae5b7
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_commit_status_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS repo_commit_status (
+    id UUID PRIMARY KEY,
+    repo UUID NOT NULL REFERENCES repo(id) ON DELETE CASCADE,
+    commit_sha TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('pending', 'success', 'failure', 'error')),
+    target_url TEXT,
+    description TEXT,
+    context TEXT NOT NULL DEFAULT 'default',
+    creator UUID NOT NULL REFERENCES "user"(id),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_commit_status_repo_sha ON repo_commit_status(repo, commit_sha);
+CREATE INDEX IF NOT EXISTS idx_commit_status_context ON repo_commit_status(repo, commit_sha, context);
diff --git a/lib/migrate/sql/repo/repo_commit_up_01.sql b/lib/migrate/sql/repo/repo_commit_up_01.sql
new file mode 100644
index 0000000..936f465
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_commit_up_01.sql
@@ -0,0 +1,14 @@
+-- depends_on: repo_committer
+CREATE TABLE IF NOT EXISTS repo_commit (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    sha TEXT NOT NULL,
+    tree_sha TEXT NOT NULL,
+    parent_shas TEXT NOT NULL,
+    author UUID NOT NULL REFERENCES repo_committer(id),
+    committer UUID NOT NULL REFERENCES repo_committer(id),
+    message TEXT NOT NULL,
+    authored_at TIMESTAMPTZ NOT NULL,
+    committed_at TIMESTAMPTZ NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
\ No newline at end of file
diff --git a/lib/migrate/sql/repo/repo_committer_down_01.sql b/lib/migrate/sql/repo/repo_committer_down_01.sql
new file mode 100644
index 0000000..df58380
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_committer_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_committer CASCADE;
diff --git a/lib/migrate/sql/repo/repo_committer_up_01.sql b/lib/migrate/sql/repo/repo_committer_up_01.sql
new file mode 100644
index 0000000..de2cd4f
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_committer_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS repo_committer (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    "user" UUID,
+    name TEXT NOT NULL,
+    email TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_deploy_key_down_01.sql b/lib/migrate/sql/repo/repo_deploy_key_down_01.sql
new file mode 100644
index 0000000..c43b410
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_deploy_key_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_deploy_key CASCADE;
diff --git a/lib/migrate/sql/repo/repo_deploy_key_up_01.sql b/lib/migrate/sql/repo/repo_deploy_key_up_01.sql
new file mode 100644
index 0000000..c4d84db
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_deploy_key_up_01.sql
@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS repo_deploy_key (
+    id BIGSERIAL PRIMARY KEY,
+    repo UUID NOT NULL REFERENCES repo(id),
+    title TEXT NOT NULL,
+    public_key TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    key_type TEXT NOT NULL,
+    key_bits INTEGER,
+    read_only BOOLEAN NOT NULL DEFAULT TRUE,
+    last_used_at TIMESTAMPTZ,
+    expires_at TIMESTAMPTZ,
+    is_revoked BOOLEAN NOT NULL DEFAULT FALSE,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_down_01.sql b/lib/migrate/sql/repo/repo_down_01.sql
new file mode 100644
index 0000000..3942f1c
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo CASCADE;
diff --git a/lib/migrate/sql/repo/repo_fork_down_01.sql b/lib/migrate/sql/repo/repo_fork_down_01.sql
new file mode 100644
index 0000000..56a017b
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_fork_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_fork CASCADE;
diff --git a/lib/migrate/sql/repo/repo_fork_up_01.sql b/lib/migrate/sql/repo/repo_fork_up_01.sql
new file mode 100644
index 0000000..1360048
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_fork_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS repo_fork (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    source_repo UUID NOT NULL,
+    forked_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_history_name_down_01.sql b/lib/migrate/sql/repo/repo_history_name_down_01.sql
new file mode 100644
index 0000000..76b515c
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_history_name_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_history_name CASCADE;
diff --git a/lib/migrate/sql/repo/repo_history_name_up_01.sql b/lib/migrate/sql/repo/repo_history_name_up_01.sql
new file mode 100644
index 0000000..07476d1
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_history_name_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS repo_history_name (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    name TEXT NOT NULL,
+    changed_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_language_down_01.sql b/lib/migrate/sql/repo/repo_language_down_01.sql
new file mode 100644
index 0000000..a716609
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_language_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_language CASCADE;
diff --git a/lib/migrate/sql/repo/repo_language_up_01.sql b/lib/migrate/sql/repo/repo_language_up_01.sql
new file mode 100644
index 0000000..46dee54
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_language_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS repo_language (
+    repo UUID NOT NULL REFERENCES repo(id),
+    language TEXT NOT NULL,
+    bytes BIGINT NOT NULL DEFAULT 0,
+    percentage REAL NOT NULL DEFAULT 0,
+    PRIMARY KEY (repo, language)
+);
diff --git a/lib/migrate/sql/repo/repo_lfs_lock_down_01.sql b/lib/migrate/sql/repo/repo_lfs_lock_down_01.sql
new file mode 100644
index 0000000..504f7fb
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_lfs_lock_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_lfs_lock CASCADE;
diff --git a/lib/migrate/sql/repo/repo_lfs_lock_up_01.sql b/lib/migrate/sql/repo/repo_lfs_lock_up_01.sql
new file mode 100644
index 0000000..67ba80d
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_lfs_lock_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS repo_lfs_lock (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    path TEXT NOT NULL,
+    locked_by UUID NOT NULL,
+    ref_name TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_lfs_object_down_01.sql b/lib/migrate/sql/repo/repo_lfs_object_down_01.sql
new file mode 100644
index 0000000..ce29cad
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_lfs_object_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_lfs_object CASCADE;
diff --git a/lib/migrate/sql/repo/repo_lfs_object_up_01.sql b/lib/migrate/sql/repo/repo_lfs_object_up_01.sql
new file mode 100644
index 0000000..5a33993
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_lfs_object_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS repo_lfs_object (
+    repo UUID NOT NULL REFERENCES repo(id),
+    oid TEXT NOT NULL,
+    size_bytes BIGINT NOT NULL DEFAULT 0,
+    storage_key TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (repo, oid)
+);
diff --git a/lib/migrate/sql/repo/repo_license_down_01.sql b/lib/migrate/sql/repo/repo_license_down_01.sql
new file mode 100644
index 0000000..0aceb8c
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_license_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_license CASCADE;
diff --git a/lib/migrate/sql/repo/repo_license_up_01.sql b/lib/migrate/sql/repo/repo_license_up_01.sql
new file mode 100644
index 0000000..958beef
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_license_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS repo_license (
+    repo UUID PRIMARY KEY REFERENCES repo(id),
+    spdx_id TEXT,
+    name TEXT NOT NULL,
+    url TEXT,
+    detected_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_lock_down_01.sql b/lib/migrate/sql/repo/repo_lock_down_01.sql
new file mode 100644
index 0000000..f0f56ea
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_lock_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_lock CASCADE;
diff --git a/lib/migrate/sql/repo/repo_lock_up_01.sql b/lib/migrate/sql/repo/repo_lock_up_01.sql
new file mode 100644
index 0000000..1166359
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_lock_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS repo_lock (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    locked_by UUID NOT NULL,
+    reason TEXT NOT NULL,
+    expires_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    released_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/repo/repo_protect_down_01.sql b/lib/migrate/sql/repo/repo_protect_down_01.sql
new file mode 100644
index 0000000..cc61b65
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_protect_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_protect CASCADE;
diff --git a/lib/migrate/sql/repo/repo_protect_up_01.sql b/lib/migrate/sql/repo/repo_protect_up_01.sql
new file mode 100644
index 0000000..3967716
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_protect_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS repo_protect (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    pattern TEXT NOT NULL,
+    require_pull_request BOOLEAN NOT NULL DEFAULT TRUE,
+    required_approvals INTEGER NOT NULL DEFAULT 1,
+    require_status_checks BOOLEAN NOT NULL DEFAULT FALSE,
+    required_status_contexts TEXT NOT NULL DEFAULT '',
+    enforce_admins BOOLEAN NOT NULL DEFAULT FALSE,
+    allow_force_pushes BOOLEAN NOT NULL DEFAULT FALSE,
+    allow_deletions BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_ref_down_01.sql b/lib/migrate/sql/repo/repo_ref_down_01.sql
new file mode 100644
index 0000000..137f78d
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_ref_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_ref CASCADE;
diff --git a/lib/migrate/sql/repo/repo_ref_up_01.sql b/lib/migrate/sql/repo/repo_ref_up_01.sql
new file mode 100644
index 0000000..6a7451c
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_ref_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS repo_ref (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    name TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    target_sha TEXT NOT NULL,
+    is_default BOOLEAN NOT NULL DEFAULT FALSE,
+    is_protected BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_release_asset_down_01.sql b/lib/migrate/sql/repo/repo_release_asset_down_01.sql
new file mode 100644
index 0000000..6c228e2
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_release_asset_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_release_asset;
\ No newline at end of file
diff --git a/lib/migrate/sql/repo/repo_release_asset_up_01.sql b/lib/migrate/sql/repo/repo_release_asset_up_01.sql
new file mode 100644
index 0000000..15b94df
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_release_asset_up_01.sql
@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS repo_release_asset (
+    id UUID PRIMARY KEY,
+    release_id UUID NOT NULL REFERENCES repo_release(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    content_type TEXT,
+    size BIGINT NOT NULL DEFAULT 0,
+    download_count BIGINT NOT NULL DEFAULT 0,
+    storage_path TEXT NOT NULL,
+    uploader UUID NOT NULL REFERENCES "user"(id),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_release_asset_release ON repo_release_asset(release_id);
diff --git a/lib/migrate/sql/repo/repo_release_down_01.sql b/lib/migrate/sql/repo/repo_release_down_01.sql
new file mode 100644
index 0000000..45d4f1c
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_release_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_release CASCADE;
diff --git a/lib/migrate/sql/repo/repo_release_up_01.sql b/lib/migrate/sql/repo/repo_release_up_01.sql
new file mode 100644
index 0000000..0795efe
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_release_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS repo_release (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    tag_name TEXT NOT NULL,
+    target_commit_sha TEXT NOT NULL,
+    name TEXT NOT NULL,
+    body TEXT,
+    draft BOOLEAN NOT NULL DEFAULT FALSE,
+    prerelease BOOLEAN NOT NULL DEFAULT FALSE,
+    author UUID NOT NULL,
+    published_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_secret_down_01.sql b/lib/migrate/sql/repo/repo_secret_down_01.sql
new file mode 100644
index 0000000..26fcc54
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_secret_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_secret CASCADE;
diff --git a/lib/migrate/sql/repo/repo_secret_up_01.sql b/lib/migrate/sql/repo/repo_secret_up_01.sql
new file mode 100644
index 0000000..34c8e3f
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_secret_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS repo_secret (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    name TEXT NOT NULL,
+    encrypted_value TEXT NOT NULL,
+    key_id TEXT NOT NULL,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_star_down_01.sql b/lib/migrate/sql/repo/repo_star_down_01.sql
new file mode 100644
index 0000000..2b922eb
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_star_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_star CASCADE;
diff --git a/lib/migrate/sql/repo/repo_star_up_01.sql b/lib/migrate/sql/repo/repo_star_up_01.sql
new file mode 100644
index 0000000..a5965e8
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_star_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS repo_star (
+    repo UUID NOT NULL REFERENCES repo(id),
+    "user" UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (repo, "user")
+);
diff --git a/lib/migrate/sql/repo/repo_topic_down_01.sql b/lib/migrate/sql/repo/repo_topic_down_01.sql
new file mode 100644
index 0000000..17bdf9c
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_topic_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_topic CASCADE;
diff --git a/lib/migrate/sql/repo/repo_topic_up_01.sql b/lib/migrate/sql/repo/repo_topic_up_01.sql
new file mode 100644
index 0000000..69d9faf
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_topic_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS repo_topic (
+    repo UUID NOT NULL REFERENCES repo(id),
+    topic TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (repo, topic)
+);
diff --git a/lib/migrate/sql/repo/repo_up_01.sql b/lib/migrate/sql/repo/repo_up_01.sql
new file mode 100644
index 0000000..6445bd8
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_up_01.sql
@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS repo (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    default_branch TEXT NOT NULL DEFAULT 'main',
+    visibility TEXT NOT NULL DEFAULT 'private',
+    size_bytes BIGINT NOT NULL DEFAULT 0,
+    is_archived BOOLEAN NOT NULL DEFAULT FALSE,
+    is_template BOOLEAN NOT NULL DEFAULT FALSE,
+    is_mirror BOOLEAN NOT NULL DEFAULT FALSE,
+    created_by UUID NOT NULL,
+    storage_path TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/repo/repo_watch_down_01.sql b/lib/migrate/sql/repo/repo_watch_down_01.sql
new file mode 100644
index 0000000..fe2b2f7
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_watch_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_watch CASCADE;
diff --git a/lib/migrate/sql/repo/repo_watch_up_01.sql b/lib/migrate/sql/repo/repo_watch_up_01.sql
new file mode 100644
index 0000000..e95dbb9
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_watch_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS repo_watch (
+    repo UUID NOT NULL REFERENCES repo(id),
+    "user" UUID NOT NULL,
+    level TEXT NOT NULL DEFAULT 'participating',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (repo, "user")
+);
diff --git a/lib/migrate/sql/repo/repo_webhook_delivery_down_01.sql b/lib/migrate/sql/repo/repo_webhook_delivery_down_01.sql
new file mode 100644
index 0000000..cc4f6e5
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_webhook_delivery_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_webhook_delivery CASCADE;
diff --git a/lib/migrate/sql/repo/repo_webhook_delivery_up_01.sql b/lib/migrate/sql/repo/repo_webhook_delivery_up_01.sql
new file mode 100644
index 0000000..20f35b6
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_webhook_delivery_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS repo_webhook_delivery (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    webhook UUID NOT NULL REFERENCES repo_webhook(id),
+    event TEXT NOT NULL,
+    request_headers TEXT,
+    request_body TEXT,
+    response_status INTEGER,
+    response_headers TEXT,
+    response_body TEXT,
+    error TEXT,
+    delivered_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/repo/repo_webhook_down_01.sql b/lib/migrate/sql/repo/repo_webhook_down_01.sql
new file mode 100644
index 0000000..9326406
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_webhook_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS repo_webhook CASCADE;
diff --git a/lib/migrate/sql/repo/repo_webhook_up_01.sql b/lib/migrate/sql/repo/repo_webhook_up_01.sql
new file mode 100644
index 0000000..6f6d98a
--- /dev/null
+++ b/lib/migrate/sql/repo/repo_webhook_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS repo_webhook (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    repo UUID NOT NULL REFERENCES repo(id),
+    url TEXT NOT NULL,
+    secret_hash TEXT,
+    events TEXT NOT NULL,
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/dm_conversation_down_01.sql b/lib/migrate/sql/room/dm_conversation_down_01.sql
new file mode 100644
index 0000000..30e712e
--- /dev/null
+++ b/lib/migrate/sql/room/dm_conversation_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS dm_conversation;
diff --git a/lib/migrate/sql/room/dm_conversation_up_01.sql b/lib/migrate/sql/room/dm_conversation_up_01.sql
new file mode 100644
index 0000000..47e3551
--- /dev/null
+++ b/lib/migrate/sql/room/dm_conversation_up_01.sql
@@ -0,0 +1,17 @@
+-- depends_on: room
+CREATE TABLE IF NOT EXISTS dm_conversation (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    room UUID NOT NULL REFERENCES room(id) ON DELETE CASCADE,
+    initiator UUID NOT NULL,
+    recipient UUID NOT NULL,
+    is_closed BOOLEAN NOT NULL DEFAULT FALSE,
+    closed_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (initiator, recipient),
+    CHECK (initiator < recipient)
+);
+
+CREATE INDEX IF NOT EXISTS idx_dm_conversation_room ON dm_conversation (room);
+CREATE INDEX IF NOT EXISTS idx_dm_conversation_initiator ON dm_conversation (initiator);
+CREATE INDEX IF NOT EXISTS idx_dm_conversation_recipient ON dm_conversation (recipient);
diff --git a/lib/migrate/sql/room/message_read_down_01.sql b/lib/migrate/sql/room/message_read_down_01.sql
new file mode 100644
index 0000000..1a6fbba
--- /dev/null
+++ b/lib/migrate/sql/room/message_read_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS message_read;
diff --git a/lib/migrate/sql/room/message_read_up_01.sql b/lib/migrate/sql/room/message_read_up_01.sql
new file mode 100644
index 0000000..7f80294
--- /dev/null
+++ b/lib/migrate/sql/room/message_read_up_01.sql
@@ -0,0 +1,12 @@
+-- depends_on: room_message
+CREATE TABLE IF NOT EXISTS message_read (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message UUID NOT NULL,
+    room UUID NOT NULL REFERENCES room(id),
+    "user" UUID NOT NULL,
+    read_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (message, "user")
+);
+
+CREATE INDEX IF NOT EXISTS idx_message_read_room_user ON message_read (room, "user");
+CREATE INDEX IF NOT EXISTS idx_message_read_message ON message_read (message);
diff --git a/lib/migrate/sql/room/message_star_down_01.sql b/lib/migrate/sql/room/message_star_down_01.sql
new file mode 100644
index 0000000..938c23a
--- /dev/null
+++ b/lib/migrate/sql/room/message_star_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS message_star;
diff --git a/lib/migrate/sql/room/message_star_up_01.sql b/lib/migrate/sql/room/message_star_up_01.sql
new file mode 100644
index 0000000..af87d00
--- /dev/null
+++ b/lib/migrate/sql/room/message_star_up_01.sql
@@ -0,0 +1,12 @@
+-- depends_on: room_message
+CREATE TABLE IF NOT EXISTS message_star (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message UUID NOT NULL,
+    room UUID NOT NULL REFERENCES room(id),
+    "user" UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (message, "user")
+);
+
+CREATE INDEX IF NOT EXISTS idx_message_star_user_room ON message_star ("user", room);
+CREATE INDEX IF NOT EXISTS idx_message_star_message ON message_star (message);
diff --git a/lib/migrate/sql/room/room_ai_down_01.sql b/lib/migrate/sql/room/room_ai_down_01.sql
new file mode 100644
index 0000000..2ecc847
--- /dev/null
+++ b/lib/migrate/sql/room/room_ai_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_ai CASCADE;
diff --git a/lib/migrate/sql/room/room_ai_up_01.sql b/lib/migrate/sql/room/room_ai_up_01.sql
new file mode 100644
index 0000000..90f2704
--- /dev/null
+++ b/lib/migrate/sql/room/room_ai_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS room_ai (
+    room UUID NOT NULL REFERENCES room(id),
+    agent_session UUID NOT NULL,
+    enabled BOOLEAN NOT NULL DEFAULT FALSE,
+    auto_reply BOOLEAN NOT NULL DEFAULT FALSE,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (room, agent_session)
+);
diff --git a/lib/migrate/sql/room/room_attachment_down_01.sql b/lib/migrate/sql/room/room_attachment_down_01.sql
new file mode 100644
index 0000000..0e9c2b7
--- /dev/null
+++ b/lib/migrate/sql/room/room_attachment_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_attachment CASCADE;
diff --git a/lib/migrate/sql/room/room_attachment_up_01.sql b/lib/migrate/sql/room/room_attachment_up_01.sql
new file mode 100644
index 0000000..16ceea7
--- /dev/null
+++ b/lib/migrate/sql/room/room_attachment_up_01.sql
@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS room_attachment (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message UUID NOT NULL,
+    seq BIGINT NOT NULL,
+    file_name TEXT NOT NULL,
+    content_type TEXT,
+    size_bytes BIGINT NOT NULL DEFAULT 0,
+    storage_key TEXT NOT NULL,
+    url TEXT,
+    uploaded_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/room_category_down_01.sql b/lib/migrate/sql/room/room_category_down_01.sql
new file mode 100644
index 0000000..a1be06a
--- /dev/null
+++ b/lib/migrate/sql/room/room_category_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_category CASCADE;
diff --git a/lib/migrate/sql/room/room_category_up_01.sql b/lib/migrate/sql/room/room_category_up_01.sql
new file mode 100644
index 0000000..e4f43d1
--- /dev/null
+++ b/lib/migrate/sql/room/room_category_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS room_category (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    name TEXT NOT NULL,
+    position INTEGER NOT NULL DEFAULT 0,
+    collapsed BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/room_down_01.sql b/lib/migrate/sql/room/room_down_01.sql
new file mode 100644
index 0000000..34f8373
--- /dev/null
+++ b/lib/migrate/sql/room/room_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room CASCADE;
diff --git a/lib/migrate/sql/room/room_mention_down_01.sql b/lib/migrate/sql/room/room_mention_down_01.sql
new file mode 100644
index 0000000..f63129d
--- /dev/null
+++ b/lib/migrate/sql/room/room_mention_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_mention CASCADE;
diff --git a/lib/migrate/sql/room/room_mention_up_01.sql b/lib/migrate/sql/room/room_mention_up_01.sql
new file mode 100644
index 0000000..fc07588
--- /dev/null
+++ b/lib/migrate/sql/room/room_mention_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS room_mention (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message UUID NOT NULL,
+    seq BIGINT NOT NULL,
+    mention_type TEXT NOT NULL,
+    target_id UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/room_message_down_01.sql b/lib/migrate/sql/room/room_message_down_01.sql
new file mode 100644
index 0000000..e49bd0d
--- /dev/null
+++ b/lib/migrate/sql/room/room_message_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_message CASCADE;
diff --git a/lib/migrate/sql/room/room_message_edit_history_down_01.sql b/lib/migrate/sql/room/room_message_edit_history_down_01.sql
new file mode 100644
index 0000000..6a51e30
--- /dev/null
+++ b/lib/migrate/sql/room/room_message_edit_history_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_message_edit_history CASCADE;
diff --git a/lib/migrate/sql/room/room_message_edit_history_up_01.sql b/lib/migrate/sql/room/room_message_edit_history_up_01.sql
new file mode 100644
index 0000000..cc3c9c7
--- /dev/null
+++ b/lib/migrate/sql/room/room_message_edit_history_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS room_message_edit_history (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message UUID NOT NULL,
+    seq BIGINT NOT NULL,
+    editor UUID NOT NULL,
+    old_content TEXT NOT NULL,
+    new_content TEXT NOT NULL,
+    edited_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/room_message_up_01.sql b/lib/migrate/sql/room/room_message_up_01.sql
new file mode 100644
index 0000000..49226c1
--- /dev/null
+++ b/lib/migrate/sql/room/room_message_up_01.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS room_message (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    room UUID NOT NULL REFERENCES room(id),
+    seq BIGINT NOT NULL,
+    thread UUID,
+    parent UUID,
+    author UUID NOT NULL,
+    content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'text',
+    pinned BOOLEAN NOT NULL DEFAULT FALSE,
+    edited_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/room/room_permission_overwrite_down_01.sql b/lib/migrate/sql/room/room_permission_overwrite_down_01.sql
new file mode 100644
index 0000000..30db0f7
--- /dev/null
+++ b/lib/migrate/sql/room/room_permission_overwrite_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_permission_overwrite CASCADE;
diff --git a/lib/migrate/sql/room/room_permission_overwrite_up_01.sql b/lib/migrate/sql/room/room_permission_overwrite_up_01.sql
new file mode 100644
index 0000000..5402777
--- /dev/null
+++ b/lib/migrate/sql/room/room_permission_overwrite_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS room_permission_overwrite (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    room UUID NOT NULL REFERENCES room(id),
+    target_type TEXT NOT NULL,
+    target_id UUID NOT NULL,
+    allow_permissions TEXT NOT NULL,
+    deny_permissions TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/room_pin_down_01.sql b/lib/migrate/sql/room/room_pin_down_01.sql
new file mode 100644
index 0000000..48fc2ed
--- /dev/null
+++ b/lib/migrate/sql/room/room_pin_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_pin CASCADE;
diff --git a/lib/migrate/sql/room/room_pin_up_01.sql b/lib/migrate/sql/room/room_pin_up_01.sql
new file mode 100644
index 0000000..a89fc25
--- /dev/null
+++ b/lib/migrate/sql/room/room_pin_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS room_pin (
+    room UUID NOT NULL REFERENCES room(id),
+    message UUID NOT NULL,
+    seq BIGINT NOT NULL,
+    pinned_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (room, message)
+);
diff --git a/lib/migrate/sql/room/room_reaction_down_01.sql b/lib/migrate/sql/room/room_reaction_down_01.sql
new file mode 100644
index 0000000..b5e4b5c
--- /dev/null
+++ b/lib/migrate/sql/room/room_reaction_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_reaction CASCADE;
diff --git a/lib/migrate/sql/room/room_reaction_up_01.sql b/lib/migrate/sql/room/room_reaction_up_01.sql
new file mode 100644
index 0000000..8806528
--- /dev/null
+++ b/lib/migrate/sql/room/room_reaction_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS room_reaction (
+    message UUID NOT NULL,
+    "user" UUID NOT NULL,
+    seq BIGINT NOT NULL,
+    reaction TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (message, "user", reaction)
+);
diff --git a/lib/migrate/sql/room/room_server_label_down_01.sql b/lib/migrate/sql/room/room_server_label_down_01.sql
new file mode 100644
index 0000000..c949eb9
--- /dev/null
+++ b/lib/migrate/sql/room/room_server_label_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_server_label CASCADE;
diff --git a/lib/migrate/sql/room/room_server_label_up_01.sql b/lib/migrate/sql/room/room_server_label_up_01.sql
new file mode 100644
index 0000000..af3f794
--- /dev/null
+++ b/lib/migrate/sql/room/room_server_label_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS room_server_label (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    name TEXT NOT NULL,
+    color TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/room/room_thread_down_01.sql b/lib/migrate/sql/room/room_thread_down_01.sql
new file mode 100644
index 0000000..d8569db
--- /dev/null
+++ b/lib/migrate/sql/room/room_thread_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS room_thread CASCADE;
diff --git a/lib/migrate/sql/room/room_thread_up_01.sql b/lib/migrate/sql/room/room_thread_up_01.sql
new file mode 100644
index 0000000..19cc5c9
--- /dev/null
+++ b/lib/migrate/sql/room/room_thread_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS room_thread (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    room UUID NOT NULL REFERENCES room(id),
+    seq BIGINT NOT NULL,
+    starter_message UUID,
+    title TEXT NOT NULL,
+    created_by UUID NOT NULL,
+    archived BOOLEAN NOT NULL DEFAULT FALSE,
+    locked BOOLEAN NOT NULL DEFAULT FALSE,
+    last_message_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    archived_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/room/room_up_01.sql b/lib/migrate/sql/room/room_up_01.sql
new file mode 100644
index 0000000..8125d48
--- /dev/null
+++ b/lib/migrate/sql/room/room_up_01.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS room (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    parent UUID,
+    name TEXT NOT NULL,
+    topic TEXT,
+    room_type TEXT NOT NULL,
+    position INTEGER NOT NULL DEFAULT 0,
+    is_private BOOLEAN NOT NULL DEFAULT FALSE,
+    is_archived BOOLEAN NOT NULL DEFAULT FALSE,
+    created_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at TIMESTAMPTZ
+);
diff --git a/lib/migrate/sql/room/system_message_down_01.sql b/lib/migrate/sql/room/system_message_down_01.sql
new file mode 100644
index 0000000..3407f97
--- /dev/null
+++ b/lib/migrate/sql/room/system_message_down_01.sql
@@ -0,0 +1,2 @@
+ALTER TABLE room_message DROP COLUMN IF EXISTS metadata;
+ALTER TABLE room_message DROP COLUMN IF EXISTS system_type;
diff --git a/lib/migrate/sql/room/system_message_up_01.sql b/lib/migrate/sql/room/system_message_up_01.sql
new file mode 100644
index 0000000..14be638
--- /dev/null
+++ b/lib/migrate/sql/room/system_message_up_01.sql
@@ -0,0 +1,10 @@
+-- depends_on: room_message
+ALTER TABLE room_message ADD COLUMN IF NOT EXISTS system_type TEXT;
+ALTER TABLE room_message ADD COLUMN IF NOT EXISTS metadata JSONB NOT NULL DEFAULT '{}';
+
+COMMENT ON COLUMN room_message.system_type IS
+  'System message type: user_joined, user_left, room_renamed, room_topic_changed, '
+  'room_archived, message_pinned, dm_created, etc. NULL for regular user messages. '
+  'Learned from Rocket.Chat MessageTypes system.';
+COMMENT ON COLUMN room_message.metadata IS
+  'Structured metadata for system messages (e.g. old_name, new_name for rename events).';
diff --git a/lib/migrate/sql/room/user_room_state_down_01.sql b/lib/migrate/sql/room/user_room_state_down_01.sql
new file mode 100644
index 0000000..5ee0469
--- /dev/null
+++ b/lib/migrate/sql/room/user_room_state_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_room_state;
diff --git a/lib/migrate/sql/room/user_room_state_up_01.sql b/lib/migrate/sql/room/user_room_state_up_01.sql
new file mode 100644
index 0000000..af9f950
--- /dev/null
+++ b/lib/migrate/sql/room/user_room_state_up_01.sql
@@ -0,0 +1,19 @@
+-- depends_on: room
+CREATE TABLE IF NOT EXISTS user_room_state (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    "user" UUID NOT NULL,
+    room UUID NOT NULL REFERENCES room(id),
+    last_read_seq BIGINT NOT NULL DEFAULT 0,
+    last_read_at TIMESTAMPTZ,
+    is_pinned BOOLEAN NOT NULL DEFAULT FALSE,
+    is_muted BOOLEAN NOT NULL DEFAULT FALSE,
+    hide_muted BOOLEAN NOT NULL DEFAULT FALSE,
+    notify_level TEXT NOT NULL DEFAULT 'all',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE ("user", room)
+);
+
+CREATE INDEX IF NOT EXISTS idx_user_room_state_user ON user_room_state ("user");
+CREATE INDEX IF NOT EXISTS idx_user_room_state_room ON user_room_state (room);
+CREATE INDEX IF NOT EXISTS idx_user_room_state_pinned ON user_room_state ("user", is_pinned) WHERE is_pinned = TRUE;
diff --git a/lib/migrate/sql/user/user_2fa_down_01.sql b/lib/migrate/sql/user/user_2fa_down_01.sql
new file mode 100644
index 0000000..8ced9a0
--- /dev/null
+++ b/lib/migrate/sql/user/user_2fa_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_2fa CASCADE;
diff --git a/lib/migrate/sql/user/user_2fa_up_01.sql b/lib/migrate/sql/user/user_2fa_up_01.sql
new file mode 100644
index 0000000..c8935d2
--- /dev/null
+++ b/lib/migrate/sql/user/user_2fa_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS user_2fa (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    secret TEXT,
+    backup_codes TEXT NOT NULL,
+    enabled BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_accessibility_down_01.sql b/lib/migrate/sql/user/user_accessibility_down_01.sql
new file mode 100644
index 0000000..3696ecf
--- /dev/null
+++ b/lib/migrate/sql/user/user_accessibility_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_accessibility CASCADE;
diff --git a/lib/migrate/sql/user/user_accessibility_up_01.sql b/lib/migrate/sql/user/user_accessibility_up_01.sql
new file mode 100644
index 0000000..cc9bbdf
--- /dev/null
+++ b/lib/migrate/sql/user/user_accessibility_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS user_accessibility (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    reduce_motion BOOLEAN NOT NULL DEFAULT FALSE,
+    high_contrast BOOLEAN NOT NULL DEFAULT FALSE,
+    screen_reader_optimized BOOLEAN NOT NULL DEFAULT FALSE,
+    font_scale_percent INTEGER NOT NULL DEFAULT 100,
+    color_blind_mode TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_appearance_down_01.sql b/lib/migrate/sql/user/user_appearance_down_01.sql
new file mode 100644
index 0000000..8d53c16
--- /dev/null
+++ b/lib/migrate/sql/user/user_appearance_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_appearance CASCADE;
diff --git a/lib/migrate/sql/user/user_appearance_up_01.sql b/lib/migrate/sql/user/user_appearance_up_01.sql
new file mode 100644
index 0000000..325d66e
--- /dev/null
+++ b/lib/migrate/sql/user/user_appearance_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS user_appearance (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    theme TEXT NOT NULL DEFAULT 'system',
+    code_theme TEXT NOT NULL DEFAULT 'default',
+    layout_density TEXT NOT NULL DEFAULT 'normal',
+    sidebar_collapsed BOOLEAN NOT NULL DEFAULT FALSE,
+    show_line_numbers BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_billing_down_01.sql b/lib/migrate/sql/user/user_billing_down_01.sql
new file mode 100644
index 0000000..1be8c62
--- /dev/null
+++ b/lib/migrate/sql/user/user_billing_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_billing CASCADE;
diff --git a/lib/migrate/sql/user/user_billing_history_down_01.sql b/lib/migrate/sql/user/user_billing_history_down_01.sql
new file mode 100644
index 0000000..8a050b6
--- /dev/null
+++ b/lib/migrate/sql/user/user_billing_history_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_billing_history CASCADE;
diff --git a/lib/migrate/sql/user/user_billing_history_up_01.sql b/lib/migrate/sql/user/user_billing_history_up_01.sql
new file mode 100644
index 0000000..07f5e1c
--- /dev/null
+++ b/lib/migrate/sql/user/user_billing_history_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS user_billing_history (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    amount NUMERIC NOT NULL,
+    currency TEXT NOT NULL,
+    reason TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_billing_up_01.sql b/lib/migrate/sql/user/user_billing_up_01.sql
new file mode 100644
index 0000000..f218651
--- /dev/null
+++ b/lib/migrate/sql/user/user_billing_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS user_billing (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    balance NUMERIC NOT NULL DEFAULT 0,
+    is_pro BOOLEAN NOT NULL DEFAULT FALSE,
+    total_supply NUMERIC NOT NULL DEFAULT 0,
+    total_supply_usable NUMERIC NOT NULL DEFAULT 0,
+    cycle_start TIMESTAMPTZ,
+    cycle_end TIMESTAMPTZ,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_blacklist_down_01.sql b/lib/migrate/sql/user/user_blacklist_down_01.sql
new file mode 100644
index 0000000..61a5b7e
--- /dev/null
+++ b/lib/migrate/sql/user/user_blacklist_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_blacklist CASCADE;
diff --git a/lib/migrate/sql/user/user_blacklist_up_01.sql b/lib/migrate/sql/user/user_blacklist_up_01.sql
new file mode 100644
index 0000000..6dfdcce
--- /dev/null
+++ b/lib/migrate/sql/user/user_blacklist_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS user_blacklist (
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    black UUID NOT NULL REFERENCES "user"(id),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY ("user", black)
+);
diff --git a/lib/migrate/sql/user/user_down_01.sql b/lib/migrate/sql/user/user_down_01.sql
new file mode 100644
index 0000000..feb4402
--- /dev/null
+++ b/lib/migrate/sql/user/user_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS "user" CASCADE;
diff --git a/lib/migrate/sql/user/user_email_down_01.sql b/lib/migrate/sql/user/user_email_down_01.sql
new file mode 100644
index 0000000..c9a324a
--- /dev/null
+++ b/lib/migrate/sql/user/user_email_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_email CASCADE;
diff --git a/lib/migrate/sql/user/user_email_up_01.sql b/lib/migrate/sql/user/user_email_up_01.sql
new file mode 100644
index 0000000..e73bae8
--- /dev/null
+++ b/lib/migrate/sql/user/user_email_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS user_email (
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    email TEXT NOT NULL,
+    active BOOLEAN NOT NULL DEFAULT FALSE,
+    last_use_login TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY ("user", email)
+);
diff --git a/lib/migrate/sql/user/user_favorite_down_01.sql b/lib/migrate/sql/user/user_favorite_down_01.sql
new file mode 100644
index 0000000..580de26
--- /dev/null
+++ b/lib/migrate/sql/user/user_favorite_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_favorite CASCADE;
diff --git a/lib/migrate/sql/user/user_favorite_up_01.sql b/lib/migrate/sql/user/user_favorite_up_01.sql
new file mode 100644
index 0000000..75d1138
--- /dev/null
+++ b/lib/migrate/sql/user/user_favorite_up_01.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS user_favorite (
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    target UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY ("user", target)
+);
diff --git a/lib/migrate/sql/user/user_gpg_key_down_01.sql b/lib/migrate/sql/user/user_gpg_key_down_01.sql
new file mode 100644
index 0000000..d12de78
--- /dev/null
+++ b/lib/migrate/sql/user/user_gpg_key_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_gpg_key CASCADE;
diff --git a/lib/migrate/sql/user/user_gpg_key_up_01.sql b/lib/migrate/sql/user/user_gpg_key_up_01.sql
new file mode 100644
index 0000000..4bebca9
--- /dev/null
+++ b/lib/migrate/sql/user/user_gpg_key_up_01.sql
@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS user_gpg_key (
+    id BIGSERIAL PRIMARY KEY,
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    title TEXT NOT NULL,
+    public_key TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    key_id TEXT NOT NULL,
+    primary_key_id TEXT,
+    emails TEXT NOT NULL,
+    is_verified BOOLEAN NOT NULL DEFAULT FALSE,
+    last_used_at TIMESTAMPTZ,
+    expires_at TIMESTAMPTZ,
+    is_revoked BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_notification_down_01.sql b/lib/migrate/sql/user/user_notification_down_01.sql
new file mode 100644
index 0000000..701f35a
--- /dev/null
+++ b/lib/migrate/sql/user/user_notification_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_notification CASCADE;
diff --git a/lib/migrate/sql/user/user_notification_up_01.sql b/lib/migrate/sql/user/user_notification_up_01.sql
new file mode 100644
index 0000000..46084e1
--- /dev/null
+++ b/lib/migrate/sql/user/user_notification_up_01.sql
@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS user_notification (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    email_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    in_app_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    push_enabled BOOLEAN NOT NULL DEFAULT FALSE,
+    digest_mode TEXT NOT NULL DEFAULT 'daily',
+    dnd_enabled BOOLEAN NOT NULL DEFAULT FALSE,
+    dnd_start_minute INTEGER,
+    dnd_end_minute INTEGER,
+    marketing_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    security_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    product_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    push_subscription_endpoint TEXT,
+    push_subscription_keys_p256dh TEXT,
+    push_subscription_keys_auth TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_password_down_01.sql b/lib/migrate/sql/user/user_password_down_01.sql
new file mode 100644
index 0000000..ae0cc9e
--- /dev/null
+++ b/lib/migrate/sql/user/user_password_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_password CASCADE;
diff --git a/lib/migrate/sql/user/user_password_reset_down_01.sql b/lib/migrate/sql/user/user_password_reset_down_01.sql
new file mode 100644
index 0000000..4d46741
--- /dev/null
+++ b/lib/migrate/sql/user/user_password_reset_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_password_reset CASCADE;
diff --git a/lib/migrate/sql/user/user_password_reset_up_01.sql b/lib/migrate/sql/user/user_password_reset_up_01.sql
new file mode 100644
index 0000000..fde446c
--- /dev/null
+++ b/lib/migrate/sql/user/user_password_reset_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS user_password_reset (
+    token TEXT PRIMARY KEY,
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    expires_at TIMESTAMPTZ NOT NULL,
+    used BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_password_up_01.sql b/lib/migrate/sql/user/user_password_up_01.sql
new file mode 100644
index 0000000..66ffb2e
--- /dev/null
+++ b/lib/migrate/sql/user/user_password_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS user_password (
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    hash TEXT NOT NULL,
+    salt TEXT NOT NULL,
+    is_active BOOLEAN NOT NULL DEFAULT TRUE,
+    reason TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY ("user", created_at)
+);
diff --git a/lib/migrate/sql/user/user_privacy_down_01.sql b/lib/migrate/sql/user/user_privacy_down_01.sql
new file mode 100644
index 0000000..a17f82c
--- /dev/null
+++ b/lib/migrate/sql/user/user_privacy_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_privacy CASCADE;
diff --git a/lib/migrate/sql/user/user_privacy_up_01.sql b/lib/migrate/sql/user/user_privacy_up_01.sql
new file mode 100644
index 0000000..964c319
--- /dev/null
+++ b/lib/migrate/sql/user/user_privacy_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS user_privacy (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    profile_visibility TEXT NOT NULL DEFAULT 'public',
+    email_visibility TEXT NOT NULL DEFAULT 'private',
+    activity_visibility TEXT NOT NULL DEFAULT 'public',
+    allow_search_indexing BOOLEAN NOT NULL DEFAULT TRUE,
+    allow_direct_messages BOOLEAN NOT NULL DEFAULT TRUE,
+    show_online_status BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_profile_down_01.sql b/lib/migrate/sql/user/user_profile_down_01.sql
new file mode 100644
index 0000000..47a090e
--- /dev/null
+++ b/lib/migrate/sql/user/user_profile_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_profile CASCADE;
diff --git a/lib/migrate/sql/user/user_profile_up_01.sql b/lib/migrate/sql/user/user_profile_up_01.sql
new file mode 100644
index 0000000..b61bef0
--- /dev/null
+++ b/lib/migrate/sql/user/user_profile_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS user_profile (
+    "user" UUID PRIMARY KEY REFERENCES "user"(id),
+    language TEXT NOT NULL DEFAULT 'en',
+    theme TEXT NOT NULL DEFAULT 'system',
+    timezone TEXT NOT NULL DEFAULT 'UTC',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_session_down_01.sql b/lib/migrate/sql/user/user_session_down_01.sql
new file mode 100644
index 0000000..b65a522
--- /dev/null
+++ b/lib/migrate/sql/user/user_session_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_session CASCADE;
diff --git a/lib/migrate/sql/user/user_session_up_01.sql b/lib/migrate/sql/user/user_session_up_01.sql
new file mode 100644
index 0000000..ae62824
--- /dev/null
+++ b/lib/migrate/sql/user/user_session_up_01.sql
@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS user_session (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    token_hash TEXT NOT NULL,
+    device_name TEXT,
+    user_agent TEXT,
+    ip_address TEXT,
+    last_seen_at TIMESTAMPTZ,
+    expires_at TIMESTAMPTZ NOT NULL,
+    is_revoked BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_ssh_key_down_01.sql b/lib/migrate/sql/user/user_ssh_key_down_01.sql
new file mode 100644
index 0000000..025fa53
--- /dev/null
+++ b/lib/migrate/sql/user/user_ssh_key_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_ssh_key CASCADE;
diff --git a/lib/migrate/sql/user/user_ssh_key_up_01.sql b/lib/migrate/sql/user/user_ssh_key_up_01.sql
new file mode 100644
index 0000000..15a88cf
--- /dev/null
+++ b/lib/migrate/sql/user/user_ssh_key_up_01.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS user_ssh_key (
+    id BIGSERIAL PRIMARY KEY,
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    title TEXT NOT NULL,
+    public_key TEXT NOT NULL,
+    fingerprint TEXT NOT NULL,
+    key_type TEXT NOT NULL,
+    key_bits INTEGER,
+    is_verified BOOLEAN NOT NULL DEFAULT FALSE,
+    last_used_at TIMESTAMPTZ,
+    expires_at TIMESTAMPTZ,
+    is_revoked BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_token_down_01.sql b/lib/migrate/sql/user/user_token_down_01.sql
new file mode 100644
index 0000000..3a2f55a
--- /dev/null
+++ b/lib/migrate/sql/user/user_token_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_token CASCADE;
diff --git a/lib/migrate/sql/user/user_token_up_01.sql b/lib/migrate/sql/user/user_token_up_01.sql
new file mode 100644
index 0000000..01ce193
--- /dev/null
+++ b/lib/migrate/sql/user/user_token_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS user_token (
+    id BIGSERIAL PRIMARY KEY,
+    "user" UUID NOT NULL REFERENCES "user"(id),
+    name TEXT NOT NULL,
+    token_hash TEXT NOT NULL,
+    scopes TEXT NOT NULL,
+    expires_at TIMESTAMPTZ,
+    is_revoked BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_up_01.sql b/lib/migrate/sql/user/user_up_01.sql
new file mode 100644
index 0000000..0c188ac
--- /dev/null
+++ b/lib/migrate/sql/user/user_up_01.sql
@@ -0,0 +1,12 @@
+CREATE TABLE IF NOT EXISTS "user" (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    username TEXT NOT NULL,
+    display_name TEXT NOT NULL,
+    avatar_url TEXT NOT NULL,
+    website_url TEXT NOT NULL,
+    allow_use BOOLEAN NOT NULL DEFAULT FALSE,
+    can_search BOOLEAN NOT NULL DEFAULT FALSE,
+    last_sign_in_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/user/user_user_notifications_compat_down_01.sql b/lib/migrate/sql/user/user_user_notifications_compat_down_01.sql
new file mode 100644
index 0000000..10ea4b9
--- /dev/null
+++ b/lib/migrate/sql/user/user_user_notifications_compat_down_01.sql
@@ -0,0 +1,9 @@
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM pg_class
+        WHERE oid = to_regclass('user_notifications') AND relkind = 'v'
+    ) THEN
+        DROP VIEW user_notifications;
+    END IF;
+END $$;
diff --git a/lib/migrate/sql/user/user_user_notifications_compat_up_01.sql b/lib/migrate/sql/user/user_user_notifications_compat_up_01.sql
new file mode 100644
index 0000000..69ac412
--- /dev/null
+++ b/lib/migrate/sql/user/user_user_notifications_compat_up_01.sql
@@ -0,0 +1,24 @@
+DO $$
+BEGIN
+    IF to_regclass('user_notifications') IS NULL THEN
+        CREATE VIEW user_notifications AS
+        SELECT
+            "user",
+            email_enabled,
+            in_app_enabled,
+            push_enabled,
+            digest_mode,
+            dnd_enabled,
+            dnd_start_minute,
+            dnd_end_minute,
+            marketing_enabled,
+            security_enabled,
+            product_enabled,
+            push_subscription_endpoint,
+            push_subscription_keys_p256dh,
+            push_subscription_keys_auth,
+            created_at,
+            updated_at
+        FROM user_notification;
+    END IF;
+END $$;
diff --git a/lib/migrate/sql/user/user_user_pass_compat_down_01.sql b/lib/migrate/sql/user/user_user_pass_compat_down_01.sql
new file mode 100644
index 0000000..3b2ecf8
--- /dev/null
+++ b/lib/migrate/sql/user/user_user_pass_compat_down_01.sql
@@ -0,0 +1,9 @@
+DO $$
+BEGIN
+    IF EXISTS (
+        SELECT 1 FROM pg_class
+        WHERE oid = to_regclass('user_pass') AND relkind = 'v'
+    ) THEN
+        DROP VIEW user_pass;
+    END IF;
+END $$;
diff --git a/lib/migrate/sql/user/user_user_pass_compat_up_01.sql b/lib/migrate/sql/user/user_user_pass_compat_up_01.sql
new file mode 100644
index 0000000..8ada6b2
--- /dev/null
+++ b/lib/migrate/sql/user/user_user_pass_compat_up_01.sql
@@ -0,0 +1,15 @@
+DO $$
+BEGIN
+    IF to_regclass('user_pass') IS NULL THEN
+        CREATE VIEW user_pass AS
+        SELECT
+            "user",
+            hash,
+            salt,
+            is_active,
+            reason,
+            created_at,
+            updated_at
+        FROM user_password;
+    END IF;
+END $$;
diff --git a/lib/migrate/sql/workspace/wk_apply_join_down_01.sql b/lib/migrate/sql/workspace/wk_apply_join_down_01.sql
new file mode 100644
index 0000000..5d5df30
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_apply_join_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_apply_join CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_apply_join_up_01.sql b/lib/migrate/sql/workspace/wk_apply_join_up_01.sql
new file mode 100644
index 0000000..bd6b0aa
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_apply_join_up_01.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS wk_apply_join (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    "user" UUID NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    question TEXT,
+    answer TEXT,
+    message TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/workspace/wk_billing_down_01.sql b/lib/migrate/sql/workspace/wk_billing_down_01.sql
new file mode 100644
index 0000000..b1eb572
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_billing_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_billing CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_billing_up_01.sql b/lib/migrate/sql/workspace/wk_billing_up_01.sql
new file mode 100644
index 0000000..888d094
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_billing_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS wk_billing (
+    wk UUID PRIMARY KEY,
+    balance NUMERIC NOT NULL DEFAULT 0,
+    total_supply NUMERIC NOT NULL DEFAULT 0,
+    total_supply_usable NUMERIC NOT NULL DEFAULT 0,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/workspace/wk_gp_member_down_01.sql b/lib/migrate/sql/workspace/wk_gp_member_down_01.sql
new file mode 100644
index 0000000..ada6080
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_gp_member_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_gp_member CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_gp_member_up_01.sql b/lib/migrate/sql/workspace/wk_gp_member_up_01.sql
new file mode 100644
index 0000000..eb8dbed
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_gp_member_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS wk_gp_member (
+    "user" UUID NOT NULL,
+    gp UUID NOT NULL,
+    join_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    leave_at TIMESTAMPTZ,
+    PRIMARY KEY ("user", gp, join_at)
+);
diff --git a/lib/migrate/sql/workspace/wk_gp_role_down_01.sql b/lib/migrate/sql/workspace/wk_gp_role_down_01.sql
new file mode 100644
index 0000000..a613596
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_gp_role_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_gp_role CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_gp_role_up_01.sql b/lib/migrate/sql/workspace/wk_gp_role_up_01.sql
new file mode 100644
index 0000000..5bd25ee
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_gp_role_up_01.sql
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS wk_gp_role (
+    wk UUID NOT NULL,
+    gp UUID NOT NULL,
+    repo_read BOOLEAN NOT NULL DEFAULT FALSE,
+    repo_write BOOLEAN NOT NULL DEFAULT FALSE,
+    channel_read BOOLEAN NOT NULL DEFAULT FALSE,
+    channel_write BOOLEAN NOT NULL DEFAULT FALSE,
+    ai_read BOOLEAN NOT NULL DEFAULT FALSE,
+    ai_write BOOLEAN NOT NULL DEFAULT FALSE,
+    pr_review BOOLEAN NOT NULL DEFAULT FALSE,
+    issues_ass BOOLEAN NOT NULL DEFAULT FALSE,
+    log_view BOOLEAN NOT NULL DEFAULT FALSE,
+    PRIMARY KEY (wk, gp)
+);
diff --git a/lib/migrate/sql/workspace/wk_group_down_01.sql b/lib/migrate/sql/workspace/wk_group_down_01.sql
new file mode 100644
index 0000000..54ed5d3
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_group_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_group CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_group_up_01.sql b/lib/migrate/sql/workspace/wk_group_up_01.sql
new file mode 100644
index 0000000..937c6cf
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_group_up_01.sql
@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS wk_group (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    wk UUID NOT NULL,
+    avatar_url TEXT,
+    is_deleted BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/workspace/wk_history_name_down_01.sql b/lib/migrate/sql/workspace/wk_history_name_down_01.sql
new file mode 100644
index 0000000..9d6a677
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_history_name_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_history_name CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_history_name_up_01.sql b/lib/migrate/sql/workspace/wk_history_name_up_01.sql
new file mode 100644
index 0000000..3d2e56d
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_history_name_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS wk_history_name (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    wk UUID NOT NULL,
+    name TEXT NOT NULL,
+    changed_by UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/workspace/wk_join_approval_down_01.sql b/lib/migrate/sql/workspace/wk_join_approval_down_01.sql
new file mode 100644
index 0000000..e1c2e1f
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_join_approval_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_join_approval CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_join_approval_up_01.sql b/lib/migrate/sql/workspace/wk_join_approval_up_01.sql
new file mode 100644
index 0000000..d1d8aaa
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_join_approval_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS wk_join_approval (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    apply UUID NOT NULL,
+    wk UUID NOT NULL,
+    "user" UUID NOT NULL,
+    approver UUID NOT NULL,
+    approved BOOLEAN NOT NULL DEFAULT FALSE,
+    reason TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/workspace/wk_join_strategy_down_01.sql b/lib/migrate/sql/workspace/wk_join_strategy_down_01.sql
new file mode 100644
index 0000000..1497e81
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_join_strategy_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_join_strategy CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_join_strategy_up_01.sql b/lib/migrate/sql/workspace/wk_join_strategy_up_01.sql
new file mode 100644
index 0000000..e1b5165
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_join_strategy_up_01.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS wk_join_strategy (
+    wk UUID PRIMARY KEY,
+    require_approval BOOLEAN NOT NULL DEFAULT TRUE,
+    require_question BOOLEAN NOT NULL DEFAULT FALSE,
+    question TEXT,
+    answer TEXT,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/sql/workspace/wk_member_down_01.sql b/lib/migrate/sql/workspace/wk_member_down_01.sql
new file mode 100644
index 0000000..2016988
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_member_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS wk_member CASCADE;
diff --git a/lib/migrate/sql/workspace/wk_member_up_01.sql b/lib/migrate/sql/workspace/wk_member_up_01.sql
new file mode 100644
index 0000000..12c160f
--- /dev/null
+++ b/lib/migrate/sql/workspace/wk_member_up_01.sql
@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS wk_member (
+    wk UUID NOT NULL,
+    "user" UUID NOT NULL,
+    owner BOOLEAN NOT NULL DEFAULT FALSE,
+    admin BOOLEAN NOT NULL DEFAULT FALSE,
+    join_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    leave_at TIMESTAMPTZ,
+    PRIMARY KEY (wk, "user")
+);
diff --git a/lib/migrate/sql/workspace/workspace_down_01.sql b/lib/migrate/sql/workspace/workspace_down_01.sql
new file mode 100644
index 0000000..ab80a64
--- /dev/null
+++ b/lib/migrate/sql/workspace/workspace_down_01.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS workspace CASCADE;
diff --git a/lib/migrate/sql/workspace/workspace_up_01.sql b/lib/migrate/sql/workspace/workspace_up_01.sql
new file mode 100644
index 0000000..ee629a9
--- /dev/null
+++ b/lib/migrate/sql/workspace/workspace_up_01.sql
@@ -0,0 +1,7 @@
+CREATE TABLE IF NOT EXISTS workspace (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    avatar_url TEXT NOT NULL DEFAULT '',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/lib/migrate/src/main.rs b/lib/migrate/src/main.rs
new file mode 100644
index 0000000..ad2867b
--- /dev/null
+++ b/lib/migrate/src/main.rs
@@ -0,0 +1,419 @@
+use anyhow::{Context, Result, bail};
+use clap::{Parser, Subcommand};
+use sqlx::postgres::PgPoolOptions;
+use std::collections::{BTreeMap, HashMap, VecDeque};
+use std::path::{Path, PathBuf};
+use tracing::info;
+
+#[derive(Parser)]
+#[command(name = "migrate", about = "Database migration tool")]
+struct Cli {
+    #[arg(short, long)]
+    database_url: String,
+
+    #[command(subcommand)]
+    command: Command,
+}
+
+#[derive(Subcommand)]
+enum Command {
+    Up,
+    Down,
+    Fresh,
+    List,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Migration {
+    domain: String,
+    table: String,
+    version: u32,
+    direction: MigrationDir,
+    path: PathBuf,
+    depends_on: Vec<String>,
+}
+
+impl Ord for Migration {
+    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+        (&self.domain, &self.table, self.version, &self.direction)
+            .cmp(&(&other.domain, &other.table, other.version, &other.direction))
+    }
+}
+
+impl PartialOrd for Migration {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+enum MigrationDir {
+    Up,
+    Down,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter("migrate=info")
+        .init();
+
+    let cli = Cli::parse();
+
+    let database_url = std::env::var("DATABASE_URL")
+        .context("DATABASE_URL must be set or provided via --database-url")?;
+
+    let pool = PgPoolOptions::new()
+        .max_connections(1)
+        .connect(&database_url)
+        .await
+        .context("Failed to connect to database")?;
+
+    let sql_root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("sql");
+
+    match cli.command {
+        Command::Up => run_up(&pool, &sql_root).await,
+        Command::Down => run_down(&pool, &sql_root).await,
+        Command::Fresh => run_fresh(&pool, &sql_root).await,
+        Command::List => run_list(&pool, &sql_root).await,
+    }
+}
+
+fn discover_migrations(sql_root: &Path) -> Result<Vec<Migration>> {
+    let mut migrations = Vec::new();
+
+    if !sql_root.exists() {
+        bail!("SQL directory not found: {}", sql_root.display());
+    }
+
+    for dir_entry in std::fs::read_dir(sql_root)? {
+        let dir = dir_entry?;
+        if !dir.file_type()?.is_dir() {
+            continue;
+        }
+        let domain = dir.file_name().to_string_lossy().to_string();
+
+        for file_entry in std::fs::read_dir(dir.path())? {
+            let file = file_entry?;
+            let path = file.path();
+            if path.extension().and_then(|e| e.to_str()) != Some("sql") {
+                continue;
+            }
+
+            let stem = path
+                .file_stem()
+                .and_then(|s| s.to_str())
+                .context("Invalid filename")?;
+
+            let (table, direction, version) = parse_migration_stem(stem)?;
+
+            let content = std::fs::read_to_string(&path)
+                .context(format!("Failed to read {path:?}"))?;
+            let depends_on = parse_depends_on(&content);
+
+            migrations.push(Migration {
+                domain: domain.clone(),
+                table,
+                version,
+                direction,
+                path,
+                depends_on,
+            });
+        }
+    }
+
+    migrations.sort();
+    Ok(migrations)
+}
+
+fn parse_migration_stem(stem: &str) -> Result<(String, MigrationDir, u32)> {
+    if let Some(pos) = stem.rfind("_up_") {
+        let table = stem[..pos].to_string();
+        let ver_str = &stem[pos + 4..];
+        let version =
+            ver_str.parse::<u32>().context("Invalid version number")?;
+        Ok((table, MigrationDir::Up, version))
+    } else if let Some(pos) = stem.rfind("_down_") {
+        let table = stem[..pos].to_string();
+        let ver_str = &stem[pos + 6..];
+        let version =
+            ver_str.parse::<u32>().context("Invalid version number")?;
+        Ok((table, MigrationDir::Down, version))
+    } else {
+        bail!("Migration filename must contain _up_ or _down_: {stem}");
+    }
+}
+
+async fn ensure_migrations_table(pool: &sqlx::PgPool) -> Result<()> {
+    sqlx::query(
+        r#"
+        CREATE TABLE IF NOT EXISTS _sql_migrations (
+            domain TEXT NOT NULL,
+            table_name TEXT NOT NULL,
+            version INTEGER NOT NULL,
+            applied_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            checksum TEXT NOT NULL DEFAULT '',
+            PRIMARY KEY (domain, table_name, version)
+        )
+        "#,
+    )
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+async fn applied_set(
+    pool: &sqlx::PgPool,
+) -> Result<BTreeMap<(String, String, u32), String>> {
+    let rows: Vec<(String, String, i32, String)> =
+        sqlx::query_as("SELECT domain, table_name, version, checksum FROM _sql_migrations ORDER BY domain, table_name, version")
+            .fetch_all(pool)
+            .await?;
+
+    Ok(rows
+        .into_iter()
+        .map(|(d, t, v, c)| ((d, t, v as u32), c))
+        .collect())
+}
+
+async fn record_migration(
+    pool: &sqlx::PgPool,
+    m: &Migration,
+    checksum: &str,
+) -> Result<()> {
+    sqlx::query(
+        r#"
+        INSERT INTO _sql_migrations (domain, table_name, version, checksum)
+        VALUES ($1, $2, $3, $4)
+        ON CONFLICT DO NOTHING
+        "#,
+    )
+    .bind(&m.domain)
+    .bind(&m.table)
+    .bind(m.version as i32)
+    .bind(checksum)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+async fn delete_migration(pool: &sqlx::PgPool, m: &Migration) -> Result<()> {
+    sqlx::query(
+        "DELETE FROM _sql_migrations WHERE domain = $1 AND table_name = $2 AND version = $3",
+    )
+    .bind(&m.domain)
+    .bind(&m.table)
+    .bind(m.version as i32)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+fn compute_checksum(content: &str) -> String {
+    use std::collections::hash_map::DefaultHasher;
+    use std::hash::{Hash, Hasher};
+    let mut hasher = DefaultHasher::new();
+    content.hash(&mut hasher);
+    format!("{:x}", hasher.finish())
+}
+
+fn parse_depends_on(content: &str) -> Vec<String> {
+    content
+        .lines()
+        .filter_map(|line| {
+            let line = line.trim();
+            line.strip_prefix("-- depends_on:")
+                .map(|deps| {
+                    deps.split(',')
+                        .map(|d| d.trim().to_string())
+                        .filter(|d| !d.is_empty())
+                        .collect::<Vec<_>>()
+                })
+        })
+        .flatten()
+        .collect()
+}
+
+fn topo_sort(migrations: &mut [Migration]) -> Result<()> {
+    let table_to_idx: HashMap<String, usize> = migrations
+        .iter()
+        .enumerate()
+        .map(|(i, m)| (m.table.clone(), i))
+        .collect();
+
+    let n = migrations.len();
+    let mut in_degree = vec![0u32; n];
+    let mut adj: Vec<Vec<usize>> = vec![Vec::new(); n];
+
+    for (i, m) in migrations.iter().enumerate() {
+        for dep in &m.depends_on {
+            if let Some(&j) = table_to_idx.get(dep) {
+                adj[j].push(i);
+                in_degree[i] += 1;
+            }
+        }
+    }
+
+    let mut queue: VecDeque<usize> = (0..n)
+        .filter(|&i| in_degree[i] == 0)
+        .collect();
+
+    let mut order = Vec::with_capacity(n);
+    while let Some(i) = queue.pop_front() {
+        order.push(i);
+        for &next in &adj[i] {
+            in_degree[next] -= 1;
+            if in_degree[next] == 0 {
+                queue.push_back(next);
+            }
+        }
+    }
+
+    if order.len() != n {
+        bail!("Circular dependency detected among migrations");
+    }
+
+    let original: Vec<Migration> = migrations.iter().cloned().collect();
+    for (slot, &idx) in order.iter().enumerate() {
+        migrations[slot] = original[idx].clone();
+    }
+
+    Ok(())
+}
+fn into_static(s: String) -> &'static str {
+    Box::leak(s.into_boxed_str())
+}
+
+async fn exec_sql(pool: &sqlx::PgPool, sql: &str) -> Result<()> {
+    sqlx::raw_sql(into_static(sql.to_owned()))
+        .execute(pool)
+        .await?;
+    Ok(())
+}
+
+async fn run_up(pool: &sqlx::PgPool, sql_root: &Path) -> Result<()> {
+    ensure_migrations_table(pool).await?;
+    let all = discover_migrations(sql_root)?;
+    let applied = applied_set(pool).await?;
+
+    let mut up_migrations: Vec<_> = all
+        .into_iter()
+        .filter(|m| m.direction == MigrationDir::Up)
+        .filter(|m| {
+            !applied.contains_key(&(
+                m.domain.clone(),
+                m.table.clone(),
+                m.version,
+            ))
+        })
+        .collect();
+
+    if up_migrations.is_empty() {
+        info!("All migrations are already applied.");
+        return Ok(());
+    }
+
+    topo_sort(&mut up_migrations)?;
+
+    for m in &up_migrations {
+        let sql = std::fs::read_to_string(&m.path)
+            .context(format!("Failed to read {:?}", m.path))?;
+        let checksum = compute_checksum(&sql);
+
+        info!("Applying {}/{}/v{}", m.domain, m.table, m.version);
+        exec_sql(pool, &sql).await?;
+        record_migration(pool, m, &checksum).await?;
+    }
+
+    info!("Applied {} migration(s).", up_migrations.len());
+    Ok(())
+}
+
+async fn run_down(pool: &sqlx::PgPool, sql_root: &Path) -> Result<()> {
+    ensure_migrations_table(pool).await?;
+    let all = discover_migrations(sql_root)?;
+    let applied = applied_set(pool).await?;
+
+    let mut down_targets: Vec<_> = all
+        .into_iter()
+        .filter(|m| m.direction == MigrationDir::Down)
+        .filter(|m| {
+            applied.contains_key(&(
+                m.domain.clone(),
+                m.table.clone(),
+                m.version,
+            ))
+        })
+        .collect();
+    down_targets.sort();
+
+    if down_targets.is_empty() {
+        info!("No migrations to roll back.");
+        return Ok(());
+    }
+
+    let m = &down_targets[down_targets.len() - 1];
+    let sql = std::fs::read_to_string(&m.path)?;
+
+    info!("Rolling back {}/{}/v{}", m.domain, m.table, m.version);
+    exec_sql(pool, &sql).await?;
+    delete_migration(pool, m).await?;
+
+    info!("Rolled back 1 migration.");
+    Ok(())
+}
+
+async fn run_fresh(pool: &sqlx::PgPool, sql_root: &Path) -> Result<()> {
+    info!("Dropping all tables and re-applying migrations...");
+
+    exec_sql(pool, "DROP TABLE IF EXISTS _sql_migrations CASCADE").await?;
+
+    let all = discover_migrations(sql_root)?;
+    let down_migrations: Vec<_> = all
+        .into_iter()
+        .filter(|m| m.direction == MigrationDir::Down)
+        .collect();
+
+    let mut drops: Vec<_> = down_migrations.iter().collect();
+    drops.sort();
+    drops.reverse();
+
+    for m in &drops {
+        let sql = std::fs::read_to_string(&m.path)?;
+        let _ = exec_sql(pool, &sql).await;
+    }
+
+    run_up(pool, sql_root).await
+}
+
+async fn run_list(pool: &sqlx::PgPool, sql_root: &Path) -> Result<()> {
+    ensure_migrations_table(pool).await?;
+    let all = discover_migrations(sql_root)?;
+    let applied = applied_set(pool).await?;
+
+    let up_migrations: Vec<_> = all
+        .into_iter()
+        .filter(|m| m.direction == MigrationDir::Up)
+        .collect();
+
+    println!(
+        "{:<20} {:<30} {:>8}  {}",
+        "Domain", "Table", "Version", "Status"
+    );
+    println!("{:-<20} {:-<30} {:-<8}  {:-<10}", "", "", "", "");
+
+    for m in &up_migrations {
+        let key = (m.domain.clone(), m.table.clone(), m.version);
+        let status = if applied.contains_key(&key) {
+            "Applied"
+        } else {
+            "Pending"
+        };
+        println!(
+            "{:<20} {:<30} {:>8}  {}",
+            m.domain, m.table, m.version, status
+        );
+    }
+
+    Ok(())
+}
diff --git a/lib/model/Cargo.toml b/lib/model/Cargo.toml
new file mode 100644
index 0000000..84400d8
--- /dev/null
+++ b/lib/model/Cargo.toml
@@ -0,0 +1,33 @@
+[package]
+name = "model"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+[lib]
+path = "lib.rs"
+name = "model"
+[dependencies]
+sqlx = { workspace = true, features = [
+    "derive",
+    "postgres",
+    "runtime-tokio",
+    "uuid",
+    "rust_decimal",
+    "chrono"
+]}
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+rust_decimal = { workspace = true, features = ["serde"] }
+uuid = { workspace = true, features = ["serde","v7"] }
+chrono = { workspace = true, features = ["serde"] }
+db = { workspace = true }
+[lints]
+workspace = true
diff --git a/lib/model/agent/agent_conversation.rs b/lib/model/agent/agent_conversation.rs
new file mode 100644
index 0000000..1761c31
--- /dev/null
+++ b/lib/model/agent/agent_conversation.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentConversationModel {
+    pub id: Uuid,
+    pub session: Uuid,
+    pub title: String,
+    pub created_by: Uuid,
+    pub last_message_at: Option<DateTime<Utc>>,
+    pub archived_at: Option<DateTime<Utc>>,
+    pub compacted_summary: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/agent/agent_knowledge_base.rs b/lib/model/agent/agent_knowledge_base.rs
new file mode 100644
index 0000000..d4fce79
--- /dev/null
+++ b/lib/model/agent/agent_knowledge_base.rs
@@ -0,0 +1,19 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentKnowledgeBaseModel {
+    pub id: Uuid,
+    pub session: Uuid,
+    pub title: String,
+    pub source_type: String,
+    pub source_url: Option<String>,
+    pub content: Option<String>,
+    pub embedding_ref: Option<String>,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/agent/agent_long_term_memories.rs b/lib/model/agent/agent_long_term_memories.rs
new file mode 100644
index 0000000..3b4ca20
--- /dev/null
+++ b/lib/model/agent/agent_long_term_memories.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentLongTermMemoryModel {
+    pub id: Uuid,
+    pub session: Uuid,
+    pub key: String,
+    pub value: String,
+    pub importance: i32,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/agent/agent_message.rs b/lib/model/agent/agent_message.rs
new file mode 100644
index 0000000..2cfd6ee
--- /dev/null
+++ b/lib/model/agent/agent_message.rs
@@ -0,0 +1,21 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentMessageModel {
+    pub id: Uuid,
+    pub conversation: Uuid,
+    pub parent: Option<Uuid>,
+    pub role: String,
+    pub author: Option<Uuid>,
+    pub content: String,
+    pub content_type: String,
+    pub status: String,
+    pub model_invocation: Option<Uuid>,
+    pub reasoning_content: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/agent/agent_message_fork.rs b/lib/model/agent/agent_message_fork.rs
new file mode 100644
index 0000000..2919483
--- /dev/null
+++ b/lib/model/agent/agent_message_fork.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentMessageForkModel {
+    pub id: Uuid,
+    pub source_message: Uuid,
+    pub forked_conversation: Uuid,
+    pub forked_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/agent/agent_model_invocations.rs b/lib/model/agent/agent_model_invocations.rs
new file mode 100644
index 0000000..ec981d7
--- /dev/null
+++ b/lib/model/agent/agent_model_invocations.rs
@@ -0,0 +1,21 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentModelInvocationModel {
+    pub id: Uuid,
+    pub session: Uuid,
+    pub conversation: Option<Uuid>,
+    pub message: Option<Uuid>,
+    pub model_version: Uuid,
+    pub request_id: Option<String>,
+    pub status: String,
+    pub prompt: Option<String>,
+    pub response: Option<String>,
+    pub error: Option<String>,
+    pub started_at: DateTime<Utc>,
+    pub finished_at: Option<DateTime<Utc>>,
+    pub latency_ms: Option<i64>,
+}
diff --git a/lib/model/agent/agent_session.rs b/lib/model/agent/agent_session.rs
new file mode 100644
index 0000000..e3c9f26
--- /dev/null
+++ b/lib/model/agent/agent_session.rs
@@ -0,0 +1,36 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentSessionModel {
+    pub id: Uuid,
+    pub user: Option<Uuid>,
+    pub wk: Option<Uuid>,
+    pub name: String,
+    pub description: Option<String>,
+    pub agent_kind: String,
+    pub model_version: Option<Uuid>,
+    pub system_prompt: Option<String>,
+    pub temperature: Option<f32>,
+    pub max_output_tokens: Option<i32>,
+    pub tool_policy: Option<String>,
+    pub knowledge_base_ids: Option<String>,
+    pub variables: Option<String>,
+    pub visibility: String,
+    pub version: i32,
+    pub published_at: Option<DateTime<Utc>>,
+    pub rollback_from_version: Option<i32>,
+    pub enabled: bool,
+    pub source: Option<String>,
+    pub parent_session_id: Option<Uuid>,
+    pub toolset_json: Option<String>,
+    pub memory_provider: Option<String>,
+    pub memory_provider_config: Option<String>,
+    pub iteration_budget: Option<i32>,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/agent/agent_subagent_session.rs b/lib/model/agent/agent_subagent_session.rs
new file mode 100644
index 0000000..d690880
--- /dev/null
+++ b/lib/model/agent/agent_subagent_session.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentSubagentSessionModel {
+    pub id: Uuid,
+    pub parent_session: Uuid,
+    pub child_session: Uuid,
+    pub name: String,
+    pub purpose: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub ended_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/agent/agent_token_usage.rs b/lib/model/agent/agent_token_usage.rs
new file mode 100644
index 0000000..0e6c144
--- /dev/null
+++ b/lib/model/agent/agent_token_usage.rs
@@ -0,0 +1,22 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::{FromRow, types::Decimal};
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentTokenUsageModel {
+    pub id: Uuid,
+    pub invocation: Uuid,
+    pub session: Uuid,
+    pub model_version: Uuid,
+    pub input_tokens: i64,
+    pub output_tokens: i64,
+    pub cached_input_tokens: i64,
+    pub cache_read_tokens: Option<i64>,
+    pub cache_write_tokens: Option<i64>,
+    pub reasoning_tokens: Option<i64>,
+    pub total_tokens: i64,
+    pub cost: Option<Decimal>,
+    pub currency: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/agent/agent_tool_call_log.rs b/lib/model/agent/agent_tool_call_log.rs
new file mode 100644
index 0000000..8934f53
--- /dev/null
+++ b/lib/model/agent/agent_tool_call_log.rs
@@ -0,0 +1,22 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentToolCallLogModel {
+    pub id: Uuid,
+    pub invocation: Option<Uuid>,
+    pub session: Uuid,
+    pub conversation: Option<Uuid>,
+    pub message: Option<Uuid>,
+    pub tool_call_id: Option<String>,
+    pub tool_name: String,
+    pub arguments: Option<String>,
+    pub result: Option<String>,
+    pub error: Option<String>,
+    pub status: String,
+    pub started_at: DateTime<Utc>,
+    pub finished_at: Option<DateTime<Utc>>,
+    pub latency_ms: Option<i64>,
+}
diff --git a/lib/model/agent/agent_trace.rs b/lib/model/agent/agent_trace.rs
new file mode 100644
index 0000000..3d13836
--- /dev/null
+++ b/lib/model/agent/agent_trace.rs
@@ -0,0 +1,33 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AgentTraceModel {
+    pub id: Uuid,
+    pub invocation: Uuid,
+    pub conversation: Uuid,
+    pub sequence: i32,
+    pub phase: String,
+    pub content: Option<String>,
+    pub tool_calls: Option<Value>,
+    pub tool_results: Option<Value>,
+    pub input_tokens: Option<i64>,
+    pub output_tokens: Option<i64>,
+    pub metadata: Option<Value>,
+    pub created_at: DateTime<Utc>,
+}
+
+impl AgentTraceModel {
+    pub fn phase_label(&self) -> &str {
+        match self.phase.as_str() {
+            "think" => "Thinking",
+            "answer" => "Answering",
+            "act" => "Acting",
+            "summarize" => "Summarizing",
+            _ => &self.phase,
+        }
+    }
+}
diff --git a/lib/model/agent/mod.rs b/lib/model/agent/mod.rs
new file mode 100644
index 0000000..37f8c1f
--- /dev/null
+++ b/lib/model/agent/mod.rs
@@ -0,0 +1,23 @@
+pub mod agent_conversation;
+pub mod agent_knowledge_base;
+pub mod agent_long_term_memories;
+pub mod agent_message;
+pub mod agent_message_fork;
+pub mod agent_model_invocations;
+pub mod agent_session;
+pub mod agent_subagent_session;
+pub mod agent_token_usage;
+pub mod agent_tool_call_log;
+pub mod agent_trace;
+
+pub use agent_conversation::AgentConversationModel;
+pub use agent_knowledge_base::AgentKnowledgeBaseModel;
+pub use agent_long_term_memories::AgentLongTermMemoryModel;
+pub use agent_message::AgentMessageModel;
+pub use agent_message_fork::AgentMessageForkModel;
+pub use agent_model_invocations::AgentModelInvocationModel;
+pub use agent_session::AgentSessionModel;
+pub use agent_subagent_session::AgentSubagentSessionModel;
+pub use agent_token_usage::AgentTokenUsageModel;
+pub use agent_tool_call_log::AgentToolCallLogModel;
+pub use agent_trace::AgentTraceModel;
diff --git a/lib/model/ai/ai_model.rs b/lib/model/ai/ai_model.rs
new file mode 100644
index 0000000..6879b66
--- /dev/null
+++ b/lib/model/ai/ai_model.rs
@@ -0,0 +1,22 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiModelModel {
+    pub id: Uuid,
+    pub provider: Uuid,
+    pub name: String,
+    pub display_name: String,
+    pub description: Option<String>,
+    pub modality: String,
+    pub context_window: Option<i32>,
+    pub input_token_limit: Option<i32>,
+    pub output_token_limit: Option<i32>,
+    pub enabled: bool,
+    pub public: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/ai/ai_model_card.rs b/lib/model/ai/ai_model_card.rs
new file mode 100644
index 0000000..bda0aab
--- /dev/null
+++ b/lib/model/ai/ai_model_card.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiModelCardModel {
+    pub model: Uuid,
+    pub overview: Option<String>,
+    pub strengths: Option<String>,
+    pub limitations: Option<String>,
+    pub safety_notes: Option<String>,
+    pub eval_summary: Option<String>,
+    pub metadata: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/ai/ai_model_discussion.rs b/lib/model/ai/ai_model_discussion.rs
new file mode 100644
index 0000000..7268474
--- /dev/null
+++ b/lib/model/ai/ai_model_discussion.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiModelDiscussionModel {
+    pub id: Uuid,
+    pub model: Uuid,
+    pub user: Uuid,
+    pub parent: Option<Uuid>,
+    pub body: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/ai/ai_model_like.rs b/lib/model/ai/ai_model_like.rs
new file mode 100644
index 0000000..2ff4362
--- /dev/null
+++ b/lib/model/ai/ai_model_like.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiModelLikeModel {
+    pub model: Uuid,
+    pub user: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/ai/ai_model_model_tag.rs b/lib/model/ai/ai_model_model_tag.rs
new file mode 100644
index 0000000..4723b0b
--- /dev/null
+++ b/lib/model/ai/ai_model_model_tag.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiModelModelTagModel {
+    pub model: Uuid,
+    pub tag: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/ai/ai_model_version.rs b/lib/model/ai/ai_model_version.rs
new file mode 100644
index 0000000..545e0cf
--- /dev/null
+++ b/lib/model/ai/ai_model_version.rs
@@ -0,0 +1,21 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::{FromRow, types::Decimal};
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiModelVersionModel {
+    pub id: Uuid,
+    pub model: Uuid,
+    pub version: String,
+    pub provider_model_name: String,
+    pub input_price_per_million: Option<Decimal>,
+    pub output_price_per_million: Option<Decimal>,
+    pub cached_input_price_per_million: Option<Decimal>,
+    pub training_cutoff: Option<String>,
+    pub released_at: Option<DateTime<Utc>>,
+    pub deprecated_at: Option<DateTime<Utc>>,
+    pub enabled: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/ai/ai_provider.rs b/lib/model/ai/ai_provider.rs
new file mode 100644
index 0000000..57505ab
--- /dev/null
+++ b/lib/model/ai/ai_provider.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct AiProviderModel {
+    pub id: Uuid,
+    pub name: String,
+    pub base_url: Option<String>,
+    pub website_url: Option<String>,
+    pub logo_url: Option<String>,
+    pub enabled: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/ai/mod.rs b/lib/model/ai/mod.rs
new file mode 100644
index 0000000..4718c87
--- /dev/null
+++ b/lib/model/ai/mod.rs
@@ -0,0 +1,15 @@
+pub mod ai_model;
+pub mod ai_model_card;
+pub mod ai_model_discussion;
+pub mod ai_model_like;
+pub mod ai_model_model_tag;
+pub mod ai_model_version;
+pub mod ai_provider;
+
+pub use ai_model::AiModelModel;
+pub use ai_model_card::AiModelCardModel;
+pub use ai_model_discussion::AiModelDiscussionModel;
+pub use ai_model_like::AiModelLikeModel;
+pub use ai_model_model_tag::AiModelModelTagModel;
+pub use ai_model_version::AiModelVersionModel;
+pub use ai_provider::AiProviderModel;
diff --git a/lib/model/issues/issue.rs b/lib/model/issues/issue.rs
new file mode 100644
index 0000000..6c8f071
--- /dev/null
+++ b/lib/model/issues/issue.rs
@@ -0,0 +1,22 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub number: i64,
+    pub title: String,
+    pub body: Option<String>,
+    pub state: String,
+    pub priority: String,
+    pub author: Uuid,
+    pub closed_by: Option<Uuid>,
+    pub closed_at: Option<DateTime<Utc>>,
+    pub due_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/issues/issue_assignee.rs b/lib/model/issues/issue_assignee.rs
new file mode 100644
index 0000000..8996932
--- /dev/null
+++ b/lib/model/issues/issue_assignee.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueAssigneeModel {
+    pub issue: Uuid,
+    pub user: Uuid,
+    pub assigned_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_comment.rs b/lib/model/issues/issue_comment.rs
new file mode 100644
index 0000000..9417d8d
--- /dev/null
+++ b/lib/model/issues/issue_comment.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueCommentModel {
+    pub id: Uuid,
+    pub issue: Uuid,
+    pub author: Uuid,
+    pub body: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/issues/issue_event.rs b/lib/model/issues/issue_event.rs
new file mode 100644
index 0000000..2829a7a
--- /dev/null
+++ b/lib/model/issues/issue_event.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueEventModel {
+    pub id: Uuid,
+    pub issue: Uuid,
+    pub actor: Option<Uuid>,
+    pub event: String,
+    pub from_value: Option<String>,
+    pub to_value: Option<String>,
+    pub metadata: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_label.rs b/lib/model/issues/issue_label.rs
new file mode 100644
index 0000000..8d08ace
--- /dev/null
+++ b/lib/model/issues/issue_label.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueLabelModel {
+    pub issue: Uuid,
+    pub label: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_milestone.rs b/lib/model/issues/issue_milestone.rs
new file mode 100644
index 0000000..7387292
--- /dev/null
+++ b/lib/model/issues/issue_milestone.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueMilestoneModel {
+    pub issue: Uuid,
+    pub milestone: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_pull_request.rs b/lib/model/issues/issue_pull_request.rs
new file mode 100644
index 0000000..d495009
--- /dev/null
+++ b/lib/model/issues/issue_pull_request.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssuePullRequestModel {
+    pub issue: Uuid,
+    pub pull_request: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_reaction.rs b/lib/model/issues/issue_reaction.rs
new file mode 100644
index 0000000..00941b2
--- /dev/null
+++ b/lib/model/issues/issue_reaction.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueReactionModel {
+    pub id: Uuid,
+    pub issue: Uuid,
+    pub comment: Option<Uuid>,
+    pub user: Uuid,
+    pub reaction: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_reference.rs b/lib/model/issues/issue_reference.rs
new file mode 100644
index 0000000..b5cf8a0
--- /dev/null
+++ b/lib/model/issues/issue_reference.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueReferenceModel {
+    pub id: Uuid,
+    pub issue: Uuid,
+    pub target_type: String,
+    pub target_id: Uuid,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/issue_repo.rs b/lib/model/issues/issue_repo.rs
new file mode 100644
index 0000000..1112d6a
--- /dev/null
+++ b/lib/model/issues/issue_repo.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct IssueRepoModel {
+    pub issue: Uuid,
+    pub repo: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/label.rs b/lib/model/issues/label.rs
new file mode 100644
index 0000000..98c71b0
--- /dev/null
+++ b/lib/model/issues/label.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct LabelModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub name: String,
+    pub color: String,
+    pub description: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/milestone.rs b/lib/model/issues/milestone.rs
new file mode 100644
index 0000000..eb09b6c
--- /dev/null
+++ b/lib/model/issues/milestone.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct MilestoneModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub title: String,
+    pub description: Option<String>,
+    pub state: String,
+    pub due_at: Option<DateTime<Utc>>,
+    pub closed_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/issues/mod.rs b/lib/model/issues/mod.rs
new file mode 100644
index 0000000..4b8c8de
--- /dev/null
+++ b/lib/model/issues/mod.rs
@@ -0,0 +1,25 @@
+pub mod issue;
+pub mod issue_assignee;
+pub mod issue_comment;
+pub mod issue_event;
+pub mod issue_label;
+pub mod issue_milestone;
+pub mod issue_pull_request;
+pub mod issue_reaction;
+pub mod issue_reference;
+pub mod issue_repo;
+pub mod label;
+pub mod milestone;
+
+pub use issue::IssueModel;
+pub use issue_assignee::IssueAssigneeModel;
+pub use issue_comment::IssueCommentModel;
+pub use issue_event::IssueEventModel;
+pub use issue_label::IssueLabelModel;
+pub use issue_milestone::IssueMilestoneModel;
+pub use issue_pull_request::IssuePullRequestModel;
+pub use issue_reaction::IssueReactionModel;
+pub use issue_reference::IssueReferenceModel;
+pub use issue_repo::IssueRepoModel;
+pub use label::LabelModel;
+pub use milestone::MilestoneModel;
diff --git a/lib/model/lib.rs b/lib/model/lib.rs
new file mode 100644
index 0000000..7cf073d
--- /dev/null
+++ b/lib/model/lib.rs
@@ -0,0 +1,18 @@
+use db::AppDatabase;
+
+pub mod agent;
+pub mod ai;
+pub mod issues;
+pub mod logs;
+pub mod notify;
+pub mod pull_request;
+pub mod repos;
+pub mod room;
+pub mod system;
+pub mod users;
+pub mod workspace;
+
+#[derive(Clone)]
+pub struct DatabaseMapper {
+    pub db: AppDatabase,
+}
diff --git a/lib/model/notify/mod.rs b/lib/model/notify/mod.rs
new file mode 100644
index 0000000..e2dc81f
--- /dev/null
+++ b/lib/model/notify/mod.rs
@@ -0,0 +1,5 @@
+pub mod user_app_notify;
+pub mod user_email_notify;
+
+pub use user_app_notify::UserAppNotifyModel;
+pub use user_email_notify::UserEmailNotifyModel;
diff --git a/lib/model/notify/user_app_notify.rs b/lib/model/notify/user_app_notify.rs
new file mode 100644
index 0000000..7ce3ba4
--- /dev/null
+++ b/lib/model/notify/user_app_notify.rs
@@ -0,0 +1,20 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserAppNotifyModel {
+    pub id: Uuid,
+    pub user: Uuid,
+    pub title: String,
+    pub body: String,
+    pub notify_type: String,
+    pub target_type: Option<String>,
+    pub target_id: Option<Uuid>,
+    pub metadata: Option<String>,
+    pub read_at: Option<DateTime<Utc>>,
+    pub archived_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/notify/user_email_notify.rs b/lib/model/notify/user_email_notify.rs
new file mode 100644
index 0000000..7694e35
--- /dev/null
+++ b/lib/model/notify/user_email_notify.rs
@@ -0,0 +1,29 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserEmailNotifyModel {
+    pub id: Uuid,
+    pub user: Uuid,
+    pub email: String,
+    pub subject: String,
+    pub template: String,
+    pub body_text: Option<String>,
+    pub body_html: Option<String>,
+    pub notify_type: String,
+    pub target_type: Option<String>,
+    pub target_id: Option<Uuid>,
+    pub metadata: Option<String>,
+    pub status: String,
+    pub provider_message_id: Option<String>,
+    pub error: Option<String>,
+    pub retry_count: i32,
+    pub queued_at: DateTime<Utc>,
+    pub sent_at: Option<DateTime<Utc>>,
+    pub delivered_at: Option<DateTime<Utc>>,
+    pub opened_at: Option<DateTime<Utc>>,
+    pub clicked_at: Option<DateTime<Utc>>,
+    pub failed_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/pull_request/mod.rs b/lib/model/pull_request/mod.rs
new file mode 100644
index 0000000..10e7b30
--- /dev/null
+++ b/lib/model/pull_request/mod.rs
@@ -0,0 +1,21 @@
+pub mod pull_request;
+pub mod pull_request_assignee;
+pub mod pull_request_comment;
+pub mod pull_request_commit;
+pub mod pull_request_label;
+pub mod pull_request_reaction;
+pub mod pull_request_review;
+pub mod pull_request_review_comment;
+pub mod pull_request_review_reaction;
+pub mod pull_request_review_request;
+
+pub use pull_request::PullRequestModel;
+pub use pull_request_assignee::PullRequestAssigneeModel;
+pub use pull_request_comment::PullRequestCommentModel;
+pub use pull_request_commit::PullRequestCommitModel;
+pub use pull_request_label::PullRequestLabelModel;
+pub use pull_request_reaction::PullRequestReactionModel;
+pub use pull_request_review::PullRequestReviewModel;
+pub use pull_request_review_comment::PullRequestReviewCommentModel;
+pub use pull_request_review_reaction::PullRequestReviewReactionModel;
+pub use pull_request_review_request::PullRequestReviewRequestModel;
diff --git a/lib/model/pull_request/pull_request.rs b/lib/model/pull_request/pull_request.rs
new file mode 100644
index 0000000..b8d1847
--- /dev/null
+++ b/lib/model/pull_request/pull_request.rs
@@ -0,0 +1,28 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub number: i64,
+    pub title: String,
+    pub body: Option<String>,
+    pub state: String,
+    pub draft: bool,
+    pub author: Uuid,
+    pub source_repo: Uuid,
+    pub source_branch: String,
+    pub source_sha: String,
+    pub target_branch: String,
+    pub target_sha: String,
+    pub merged_by: Option<Uuid>,
+    pub merged_at: Option<DateTime<Utc>>,
+    pub closed_by: Option<Uuid>,
+    pub closed_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/pull_request/pull_request_assignee.rs b/lib/model/pull_request/pull_request_assignee.rs
new file mode 100644
index 0000000..db6b91d
--- /dev/null
+++ b/lib/model/pull_request/pull_request_assignee.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestAssigneeModel {
+    pub pull_request: Uuid,
+    pub user: Uuid,
+    pub assigned_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/pull_request/pull_request_comment.rs b/lib/model/pull_request/pull_request_comment.rs
new file mode 100644
index 0000000..7f21947
--- /dev/null
+++ b/lib/model/pull_request/pull_request_comment.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestCommentModel {
+    pub id: Uuid,
+    pub pull_request: Uuid,
+    pub author: Uuid,
+    pub body: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/pull_request/pull_request_commit.rs b/lib/model/pull_request/pull_request_commit.rs
new file mode 100644
index 0000000..22f591f
--- /dev/null
+++ b/lib/model/pull_request/pull_request_commit.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestCommitModel {
+    pub pull_request: Uuid,
+    pub commit: Uuid,
+    pub sha: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/pull_request/pull_request_label.rs b/lib/model/pull_request/pull_request_label.rs
new file mode 100644
index 0000000..f54cf03
--- /dev/null
+++ b/lib/model/pull_request/pull_request_label.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestLabelModel {
+    pub pull_request: Uuid,
+    pub label: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/pull_request/pull_request_reaction.rs b/lib/model/pull_request/pull_request_reaction.rs
new file mode 100644
index 0000000..33e3f87
--- /dev/null
+++ b/lib/model/pull_request/pull_request_reaction.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestReactionModel {
+    pub id: Uuid,
+    pub pull_request: Uuid,
+    pub comment: Option<Uuid>,
+    pub user: Uuid,
+    pub reaction: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/pull_request/pull_request_review.rs b/lib/model/pull_request/pull_request_review.rs
new file mode 100644
index 0000000..b311df5
--- /dev/null
+++ b/lib/model/pull_request/pull_request_review.rs
@@ -0,0 +1,20 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestReviewModel {
+    pub id: Uuid,
+    pub pull_request: Uuid,
+    pub reviewer: Uuid,
+    pub state: String,
+    pub body: Option<String>,
+    pub commit_sha: Option<String>,
+    pub submitted_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub dismissed_by: Option<Uuid>,
+    pub dismissed_at: Option<DateTime<Utc>>,
+    pub dismiss_reason: Option<String>,
+}
diff --git a/lib/model/pull_request/pull_request_review_comment.rs b/lib/model/pull_request/pull_request_review_comment.rs
new file mode 100644
index 0000000..e8f1aae
--- /dev/null
+++ b/lib/model/pull_request/pull_request_review_comment.rs
@@ -0,0 +1,25 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestReviewCommentModel {
+    pub id: Uuid,
+    pub pull_request: Uuid,
+    pub review: Option<Uuid>,
+    pub author: Uuid,
+    pub body: String,
+    pub path: String,
+    pub commit_sha: String,
+    pub original_commit_sha: Option<String>,
+    pub line: Option<i32>,
+    pub original_line: Option<i32>,
+    pub side: Option<String>,
+    pub resolved: bool,
+    pub resolved_by: Option<Uuid>,
+    pub resolved_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/pull_request/pull_request_review_reaction.rs b/lib/model/pull_request/pull_request_review_reaction.rs
new file mode 100644
index 0000000..409631b
--- /dev/null
+++ b/lib/model/pull_request/pull_request_review_reaction.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestReviewReactionModel {
+    pub id: Uuid,
+    pub review_comment: Uuid,
+    pub user: Uuid,
+    pub reaction: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/pull_request/pull_request_review_request.rs b/lib/model/pull_request/pull_request_review_request.rs
new file mode 100644
index 0000000..98b6125
--- /dev/null
+++ b/lib/model/pull_request/pull_request_review_request.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct PullRequestReviewRequestModel {
+    pub pull_request: Uuid,
+    pub reviewer: Option<Uuid>,
+    pub group: Option<Uuid>,
+    pub requested_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub removed_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/repos/mod.rs b/lib/model/repos/mod.rs
new file mode 100644
index 0000000..f142237
--- /dev/null
+++ b/lib/model/repos/mod.rs
@@ -0,0 +1,47 @@
+pub mod repo;
+pub mod repo_audit_log;
+pub mod repo_commit;
+pub mod repo_commit_status;
+pub mod repo_committer;
+pub mod repo_deploy_key;
+pub mod repo_fork;
+pub mod repo_history_name;
+pub mod repo_language;
+pub mod repo_lfs_lock;
+pub mod repo_lfs_object;
+pub mod repo_license;
+pub mod repo_lock;
+pub mod repo_protect;
+pub mod repo_ref;
+pub mod repo_release;
+pub mod repo_release_asset;
+pub mod repo_secret;
+pub mod repo_star;
+pub mod repo_topic;
+pub mod repo_watch;
+pub mod repo_webhook;
+pub mod repo_webhook_delivery;
+
+pub use repo::RepoModel;
+pub use repo_audit_log::RepoAuditLogModel;
+pub use repo_commit::RepoCommitModel;
+pub use repo_committer::RepoCommitterModel;
+pub use repo_deploy_key::RepoDeployKeyModel;
+pub use repo_fork::RepoForkModel;
+pub use repo_history_name::RepoHistoryNameModel;
+pub use repo_language::RepoLanguageModel;
+pub use repo_lfs_lock::RepoLfsLockModel;
+pub use repo_lfs_object::RepoLfsObjectModel;
+pub use repo_license::RepoLicenseModel;
+pub use repo_lock::RepoLockModel;
+pub use repo_protect::RepoProtectModel;
+pub use repo_ref::RepoRefModel;
+pub use repo_release::RepoReleaseModel;
+pub use repo_release_asset::RepoReleaseAssetModel;
+pub use repo_commit_status::RepoCommitStatusModel;
+pub use repo_secret::RepoSecretModel;
+pub use repo_star::RepoStarModel;
+pub use repo_topic::RepoTopicModel;
+pub use repo_watch::RepoWatchModel;
+pub use repo_webhook::RepoWebhookModel;
+pub use repo_webhook_delivery::RepoWebhookDeliveryModel;
diff --git a/lib/model/repos/repo.rs b/lib/model/repos/repo.rs
new file mode 100644
index 0000000..e855b4b
--- /dev/null
+++ b/lib/model/repos/repo.rs
@@ -0,0 +1,23 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub name: String,
+    pub description: Option<String>,
+    pub default_branch: String,
+    pub visibility: String,
+    pub size_bytes: i64,
+    pub is_archived: bool,
+    pub is_template: bool,
+    pub is_mirror: bool,
+    pub created_by: Uuid,
+    pub storage_path: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/repos/repo_audit_log.rs b/lib/model/repos/repo_audit_log.rs
new file mode 100644
index 0000000..0d36141
--- /dev/null
+++ b/lib/model/repos/repo_audit_log.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoAuditLogModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub actor: Option<Uuid>,
+    pub action: String,
+    pub target_type: String,
+    pub target_id: Option<String>,
+    pub ip_address: Option<String>,
+    pub user_agent: Option<String>,
+    pub metadata: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_commit.rs b/lib/model/repos/repo_commit.rs
new file mode 100644
index 0000000..e4337bd
--- /dev/null
+++ b/lib/model/repos/repo_commit.rs
@@ -0,0 +1,19 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoCommitModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub sha: String,
+    pub tree_sha: String,
+    pub parent_shas: String,
+    pub author: Uuid,
+    pub committer: Uuid,
+    pub message: String,
+    pub authored_at: DateTime<Utc>,
+    pub committed_at: DateTime<Utc>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_commit_status.rs b/lib/model/repos/repo_commit_status.rs
new file mode 100644
index 0000000..bc4d239
--- /dev/null
+++ b/lib/model/repos/repo_commit_status.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoCommitStatusModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub commit_sha: String,
+    pub state: String,
+    pub target_url: Option<String>,
+    pub description: Option<String>,
+    pub context: String,
+    pub creator: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_committer.rs b/lib/model/repos/repo_committer.rs
new file mode 100644
index 0000000..c8d069b
--- /dev/null
+++ b/lib/model/repos/repo_committer.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoCommitterModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub user: Option<Uuid>,
+    pub name: String,
+    pub email: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_deploy_key.rs b/lib/model/repos/repo_deploy_key.rs
new file mode 100644
index 0000000..9a6cef5
--- /dev/null
+++ b/lib/model/repos/repo_deploy_key.rs
@@ -0,0 +1,22 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoDeployKeyModel {
+    pub id: i64,
+    pub repo: Uuid,
+    pub title: String,
+    pub public_key: String,
+    pub fingerprint: String,
+    pub key_type: String,
+    pub key_bits: Option<i32>,
+    pub read_only: bool,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub is_revoked: bool,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_fork.rs b/lib/model/repos/repo_fork.rs
new file mode 100644
index 0000000..6893747
--- /dev/null
+++ b/lib/model/repos/repo_fork.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoForkModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub source_repo: Uuid,
+    pub forked_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_history_name.rs b/lib/model/repos/repo_history_name.rs
new file mode 100644
index 0000000..ebb2647
--- /dev/null
+++ b/lib/model/repos/repo_history_name.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoHistoryNameModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub name: String,
+    pub changed_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_language.rs b/lib/model/repos/repo_language.rs
new file mode 100644
index 0000000..5cb13ca
--- /dev/null
+++ b/lib/model/repos/repo_language.rs
@@ -0,0 +1,11 @@
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoLanguageModel {
+    pub repo: Uuid,
+    pub language: String,
+    pub bytes: i64,
+    pub percentage: f32,
+}
diff --git a/lib/model/repos/repo_lfs_lock.rs b/lib/model/repos/repo_lfs_lock.rs
new file mode 100644
index 0000000..fb46f23
--- /dev/null
+++ b/lib/model/repos/repo_lfs_lock.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoLfsLockModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub path: String,
+    pub locked_by: Uuid,
+    pub ref_name: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_lfs_object.rs b/lib/model/repos/repo_lfs_object.rs
new file mode 100644
index 0000000..b5faf04
--- /dev/null
+++ b/lib/model/repos/repo_lfs_object.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoLfsObjectModel {
+    pub repo: Uuid,
+    pub oid: String,
+    pub size_bytes: i64,
+    pub storage_key: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_license.rs b/lib/model/repos/repo_license.rs
new file mode 100644
index 0000000..a929812
--- /dev/null
+++ b/lib/model/repos/repo_license.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoLicenseModel {
+    pub repo: Uuid,
+    pub spdx_id: Option<String>,
+    pub name: String,
+    pub url: Option<String>,
+    pub detected_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_lock.rs b/lib/model/repos/repo_lock.rs
new file mode 100644
index 0000000..117c313
--- /dev/null
+++ b/lib/model/repos/repo_lock.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoLockModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub locked_by: Uuid,
+    pub reason: String,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub released_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/repos/repo_protect.rs b/lib/model/repos/repo_protect.rs
new file mode 100644
index 0000000..b6e2b00
--- /dev/null
+++ b/lib/model/repos/repo_protect.rs
@@ -0,0 +1,20 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoProtectModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub pattern: String,
+    pub require_pull_request: bool,
+    pub required_approvals: i32,
+    pub require_status_checks: bool,
+    pub required_status_contexts: String,
+    pub enforce_admins: bool,
+    pub allow_force_pushes: bool,
+    pub allow_deletions: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_ref.rs b/lib/model/repos/repo_ref.rs
new file mode 100644
index 0000000..497a795
--- /dev/null
+++ b/lib/model/repos/repo_ref.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoRefModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub name: String,
+    pub kind: String,
+    pub target_sha: String,
+    pub is_default: bool,
+    pub is_protected: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_release.rs b/lib/model/repos/repo_release.rs
new file mode 100644
index 0000000..9ef581f
--- /dev/null
+++ b/lib/model/repos/repo_release.rs
@@ -0,0 +1,20 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoReleaseModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub tag_name: String,
+    pub target_commit_sha: String,
+    pub name: String,
+    pub body: Option<String>,
+    pub draft: bool,
+    pub prerelease: bool,
+    pub author: Uuid,
+    pub published_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_release_asset.rs b/lib/model/repos/repo_release_asset.rs
new file mode 100644
index 0000000..5f7997c
--- /dev/null
+++ b/lib/model/repos/repo_release_asset.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoReleaseAssetModel {
+    pub id: Uuid,
+    pub release_id: Uuid,
+    pub name: String,
+    pub content_type: Option<String>,
+    pub size: i64,
+    pub download_count: i64,
+    pub storage_path: String,
+    pub uploader: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_secret.rs b/lib/model/repos/repo_secret.rs
new file mode 100644
index 0000000..500ec58
--- /dev/null
+++ b/lib/model/repos/repo_secret.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoSecretModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub name: String,
+    pub encrypted_value: String,
+    pub key_id: String,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_star.rs b/lib/model/repos/repo_star.rs
new file mode 100644
index 0000000..276dc4b
--- /dev/null
+++ b/lib/model/repos/repo_star.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoStarModel {
+    pub repo: Uuid,
+    pub user: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_topic.rs b/lib/model/repos/repo_topic.rs
new file mode 100644
index 0000000..842a6a2
--- /dev/null
+++ b/lib/model/repos/repo_topic.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoTopicModel {
+    pub repo: Uuid,
+    pub topic: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_watch.rs b/lib/model/repos/repo_watch.rs
new file mode 100644
index 0000000..e74a9d4
--- /dev/null
+++ b/lib/model/repos/repo_watch.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoWatchModel {
+    pub repo: Uuid,
+    pub user: Uuid,
+    pub level: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_webhook.rs b/lib/model/repos/repo_webhook.rs
new file mode 100644
index 0000000..fb68fd0
--- /dev/null
+++ b/lib/model/repos/repo_webhook.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoWebhookModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub url: String,
+    pub secret_hash: Option<String>,
+    pub events: String,
+    pub active: bool,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/repos/repo_webhook_delivery.rs b/lib/model/repos/repo_webhook_delivery.rs
new file mode 100644
index 0000000..f8fd7a5
--- /dev/null
+++ b/lib/model/repos/repo_webhook_delivery.rs
@@ -0,0 +1,20 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RepoWebhookDeliveryModel {
+    pub id: Uuid,
+    pub repo: Uuid,
+    pub webhook: Uuid,
+    pub event: String,
+    pub request_headers: Option<String>,
+    pub request_body: Option<String>,
+    pub response_status: Option<i32>,
+    pub response_headers: Option<String>,
+    pub response_body: Option<String>,
+    pub error: Option<String>,
+    pub delivered_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/dm_conversation.rs b/lib/model/room/dm_conversation.rs
new file mode 100644
index 0000000..2e37242
--- /dev/null
+++ b/lib/model/room/dm_conversation.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct DmConversationModel {
+    pub id: Uuid,
+    pub room: Uuid,
+    pub initiator: Uuid,
+    pub recipient: Uuid,
+    pub is_closed: bool,
+    pub closed_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/message_read.rs b/lib/model/room/message_read.rs
new file mode 100644
index 0000000..bf0d1c8
--- /dev/null
+++ b/lib/model/room/message_read.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct MessageReadModel {
+    pub id: Uuid,
+    pub message: Uuid,
+    pub room: Uuid,
+    pub user: Uuid,
+    pub read_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/message_star.rs b/lib/model/room/message_star.rs
new file mode 100644
index 0000000..d28332e
--- /dev/null
+++ b/lib/model/room/message_star.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct MessageStarModel {
+    pub id: Uuid,
+    pub message: Uuid,
+    pub room: Uuid,
+    pub user: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/mod.rs b/lib/model/room/mod.rs
new file mode 100644
index 0000000..2b511c8
--- /dev/null
+++ b/lib/model/room/mod.rs
@@ -0,0 +1,33 @@
+pub mod room;
+pub mod room_ai;
+pub mod room_attachments;
+pub mod room_categories;
+pub mod room_message;
+pub mod room_message_edit_history;
+pub mod room_permission_overwrite;
+pub mod room_pins;
+pub mod room_reactions;
+pub mod room_server_label;
+pub mod room_threads;
+pub mod room_mention;
+pub mod user_room_state;
+pub mod dm_conversation;
+pub mod message_read;
+pub mod message_star;
+
+pub use room::RoomModel;
+pub use room_ai::RoomAiModel;
+pub use room_attachments::RoomAttachmentModel;
+pub use room_categories::RoomCategoryModel;
+pub use room_mention::RoomMentionModel;
+pub use room_message::RoomMessageModel;
+pub use room_message_edit_history::RoomMessageEditHistoryModel;
+pub use room_permission_overwrite::RoomPermissionOverwriteModel;
+pub use room_pins::RoomPinModel;
+pub use room_reactions::RoomReactionModel;
+pub use room_server_label::RoomServerLabelModel;
+pub use room_threads::RoomThreadModel;
+pub use user_room_state::UserRoomStateModel;
+pub use dm_conversation::DmConversationModel;
+pub use message_read::MessageReadModel;
+pub use message_star::MessageStarModel;
diff --git a/lib/model/room/room.rs b/lib/model/room/room.rs
new file mode 100644
index 0000000..8d629b5
--- /dev/null
+++ b/lib/model/room/room.rs
@@ -0,0 +1,21 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub parent: Option<Uuid>,
+    pub name: String,
+    pub topic: Option<String>,
+    pub room_type: String,
+    pub position: i32,
+    pub is_private: bool,
+    pub is_archived: bool,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/room/room_ai.rs b/lib/model/room/room_ai.rs
new file mode 100644
index 0000000..69eea18
--- /dev/null
+++ b/lib/model/room/room_ai.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomAiModel {
+    pub room: Uuid,
+    pub agent_session: Uuid,
+    pub enabled: bool,
+    pub auto_reply: bool,
+    pub created_by: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_attachments.rs b/lib/model/room/room_attachments.rs
new file mode 100644
index 0000000..58cb77e
--- /dev/null
+++ b/lib/model/room/room_attachments.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomAttachmentModel {
+    pub id: Uuid,
+    pub message: Uuid,
+    pub seq: i64,
+    pub file_name: String,
+    pub content_type: Option<String>,
+    pub size_bytes: i64,
+    pub storage_key: String,
+    pub url: Option<String>,
+    pub uploaded_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_categories.rs b/lib/model/room/room_categories.rs
new file mode 100644
index 0000000..7136d7a
--- /dev/null
+++ b/lib/model/room/room_categories.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomCategoryModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub name: String,
+    pub position: i32,
+    pub collapsed: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_mention.rs b/lib/model/room/room_mention.rs
new file mode 100644
index 0000000..2e73bf0
--- /dev/null
+++ b/lib/model/room/room_mention.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomMentionModel {
+    pub id: Uuid,
+    pub message: Uuid,
+    pub seq: i64,
+    pub mention_type: String,
+    pub target_id: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_message.rs b/lib/model/room/room_message.rs
new file mode 100644
index 0000000..7473a06
--- /dev/null
+++ b/lib/model/room/room_message.rs
@@ -0,0 +1,25 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomMessageModel {
+    pub id: Uuid,
+    pub room: Uuid,
+    pub seq: i64,
+    pub thread: Option<Uuid>,
+    pub parent: Option<Uuid>,
+    pub author: Uuid,
+    pub content: String,
+    pub content_type: String,
+    pub pinned: bool,
+    pub system_type: Option<String>,
+    #[serde(default)]
+    pub metadata: Value,
+    pub edited_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub deleted_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/room/room_message_edit_history.rs b/lib/model/room/room_message_edit_history.rs
new file mode 100644
index 0000000..d373d54
--- /dev/null
+++ b/lib/model/room/room_message_edit_history.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomMessageEditHistoryModel {
+    pub id: Uuid,
+    pub message: Uuid,
+    pub seq: i64,
+    pub editor: Uuid,
+    pub old_content: String,
+    pub new_content: String,
+    pub edited_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_permission_overwrite.rs b/lib/model/room/room_permission_overwrite.rs
new file mode 100644
index 0000000..6286eb6
--- /dev/null
+++ b/lib/model/room/room_permission_overwrite.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomPermissionOverwriteModel {
+    pub id: Uuid,
+    pub room: Uuid,
+    pub target_type: String,
+    pub target_id: Uuid,
+    pub allow: String,
+    pub deny: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_pins.rs b/lib/model/room/room_pins.rs
new file mode 100644
index 0000000..f5d50b2
--- /dev/null
+++ b/lib/model/room/room_pins.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomPinModel {
+    pub room: Uuid,
+    pub message: Uuid,
+    pub seq: i64,
+    pub pinned_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_reactions.rs b/lib/model/room/room_reactions.rs
new file mode 100644
index 0000000..aeba374
--- /dev/null
+++ b/lib/model/room/room_reactions.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomReactionModel {
+    pub message: Uuid,
+    pub user: Uuid,
+    pub seq: i64,
+    pub reaction: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_server_label.rs b/lib/model/room/room_server_label.rs
new file mode 100644
index 0000000..3548ec1
--- /dev/null
+++ b/lib/model/room/room_server_label.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomServerLabelModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub name: String,
+    pub color: String,
+    pub description: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/room/room_threads.rs b/lib/model/room/room_threads.rs
new file mode 100644
index 0000000..fb71547
--- /dev/null
+++ b/lib/model/room/room_threads.rs
@@ -0,0 +1,20 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct RoomThreadModel {
+    pub id: Uuid,
+    pub room: Uuid,
+    pub seq: i64,
+    pub starter_message: Option<Uuid>,
+    pub title: String,
+    pub created_by: Uuid,
+    pub archived: bool,
+    pub locked: bool,
+    pub last_message_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+    pub archived_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/room/user_room_state.rs b/lib/model/room/user_room_state.rs
new file mode 100644
index 0000000..611377a
--- /dev/null
+++ b/lib/model/room/user_room_state.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserRoomStateModel {
+    pub id: Uuid,
+    pub user: Uuid,
+    pub room: Uuid,
+    pub last_read_seq: i64,
+    pub last_read_at: Option<DateTime<Utc>>,
+    pub is_pinned: bool,
+    pub is_muted: bool,
+    pub hide_muted: bool,
+    pub notify_level: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/system/mod.rs b/lib/model/system/mod.rs
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/lib/model/system/mod.rs
@@ -0,0 +1 @@
+
diff --git a/lib/model/users/mod.rs b/lib/model/users/mod.rs
new file mode 100644
index 0000000..fd6be7f
--- /dev/null
+++ b/lib/model/users/mod.rs
@@ -0,0 +1,37 @@
+pub mod user;
+pub mod user_2fa;
+pub mod user_accessibility;
+pub mod user_appearance;
+pub mod user_billing;
+pub mod user_billing_history;
+pub mod user_blacklist;
+pub mod user_email;
+pub mod user_favorite;
+pub mod user_gpg_key;
+pub mod user_notifications;
+pub mod user_pass;
+pub mod user_passreset;
+pub mod user_privacy;
+pub mod user_profile;
+pub mod user_session;
+pub mod user_ssh_key;
+pub mod user_token;
+
+pub use user::UserModel;
+pub use user_2fa::User2FaModel;
+pub use user_accessibility::UserAccessibilityModel;
+pub use user_appearance::UserAppearanceModel;
+pub use user_billing::UserBillingModel;
+pub use user_billing_history::UserBillingHistoryModel;
+pub use user_blacklist::UserBlacklistModel;
+pub use user_email::UserEmailModel;
+pub use user_favorite::UserFavoriteModel;
+pub use user_gpg_key::UserGpgKeyModel;
+pub use user_notifications::UserNotificationModel;
+pub use user_pass::UserPasswordModel;
+pub use user_passreset::UserPasswordResetModel;
+pub use user_privacy::UserPrivacyModel;
+pub use user_profile::UserProfileModel;
+pub use user_session::UserSessionModel;
+pub use user_ssh_key::UserSshKeyModel;
+pub use user_token::UserTokenModel;
diff --git a/lib/model/users/user.rs b/lib/model/users/user.rs
new file mode 100644
index 0000000..dffa0e3
--- /dev/null
+++ b/lib/model/users/user.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserModel {
+    pub id: Uuid,
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+    pub website_url: String,
+    pub allow_use: bool,
+    pub can_search: bool,
+    pub last_sign_in_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_2fa.rs b/lib/model/users/user_2fa.rs
new file mode 100644
index 0000000..b3a3981
--- /dev/null
+++ b/lib/model/users/user_2fa.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct User2FaModel {
+    pub user: Uuid,
+    pub secret: Option<String>,
+    pub backup_codes: String,
+    pub enabled: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_accessibility.rs b/lib/model/users/user_accessibility.rs
new file mode 100644
index 0000000..86db5cd
--- /dev/null
+++ b/lib/model/users/user_accessibility.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserAccessibilityModel {
+    pub user: Uuid,
+    pub reduce_motion: bool,
+    pub high_contrast: bool,
+    pub screen_reader_optimized: bool,
+    pub font_scale_percent: i32,
+    pub color_blind_mode: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_appearance.rs b/lib/model/users/user_appearance.rs
new file mode 100644
index 0000000..ff8fd2d
--- /dev/null
+++ b/lib/model/users/user_appearance.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserAppearanceModel {
+    pub user: Uuid,
+    pub theme: String,
+    pub code_theme: String,
+    pub layout_density: String,
+    pub sidebar_collapsed: bool,
+    pub show_line_numbers: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_billing.rs b/lib/model/users/user_billing.rs
new file mode 100644
index 0000000..57ba865
--- /dev/null
+++ b/lib/model/users/user_billing.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::{FromRow, types::Decimal};
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserBillingModel {
+    pub user: Uuid,
+    pub balance: Decimal,
+    pub is_pro: bool,
+    pub total_supply: Decimal,
+    pub total_supply_usable: Decimal,
+    pub cycle_start: Option<DateTime<Utc>>,
+    pub cycle_end: Option<DateTime<Utc>>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_billing_history.rs b/lib/model/users/user_billing_history.rs
new file mode 100644
index 0000000..07d69fb
--- /dev/null
+++ b/lib/model/users/user_billing_history.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::{FromRow, types::Decimal};
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserBillingHistoryModel {
+    pub id: Uuid,
+    pub user: Uuid,
+    pub amount: Decimal,
+    pub currency: String,
+    pub reason: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_blacklist.rs b/lib/model/users/user_blacklist.rs
new file mode 100644
index 0000000..1841d19
--- /dev/null
+++ b/lib/model/users/user_blacklist.rs
@@ -0,0 +1,11 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserBlacklistModel {
+    pub user: Uuid,
+    pub black: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_email.rs b/lib/model/users/user_email.rs
new file mode 100644
index 0000000..2b60b61
--- /dev/null
+++ b/lib/model/users/user_email.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserEmailModel {
+    pub user: Uuid,
+    pub email: String,
+    pub created_at: DateTime<Utc>,
+    pub active: bool,
+    pub last_use_login: Option<DateTime<Utc>>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_favorite.rs b/lib/model/users/user_favorite.rs
new file mode 100644
index 0000000..dd794bb
--- /dev/null
+++ b/lib/model/users/user_favorite.rs
@@ -0,0 +1,10 @@
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserFavoriteModel {
+    pub user: Uuid,
+    pub target: Uuid,
+    pub created_at: Uuid,
+}
diff --git a/lib/model/users/user_gpg_key.rs b/lib/model/users/user_gpg_key.rs
new file mode 100644
index 0000000..dd5348a
--- /dev/null
+++ b/lib/model/users/user_gpg_key.rs
@@ -0,0 +1,22 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserGpgKeyModel {
+    pub id: i64,
+    pub user: Uuid,
+    pub title: String,
+    pub public_key: String,
+    pub fingerprint: String,
+    pub key_id: String,
+    pub primary_key_id: Option<String>,
+    pub emails: String,
+    pub is_verified: bool,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub is_revoked: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_notifications.rs b/lib/model/users/user_notifications.rs
new file mode 100644
index 0000000..701a4a3
--- /dev/null
+++ b/lib/model/users/user_notifications.rs
@@ -0,0 +1,24 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserNotificationModel {
+    pub user: Uuid,
+    pub email_enabled: bool,
+    pub in_app_enabled: bool,
+    pub push_enabled: bool,
+    pub digest_mode: String,
+    pub dnd_enabled: bool,
+    pub dnd_start_minute: Option<i32>,
+    pub dnd_end_minute: Option<i32>,
+    pub marketing_enabled: bool,
+    pub security_enabled: bool,
+    pub product_enabled: bool,
+    pub push_subscription_endpoint: Option<String>,
+    pub push_subscription_keys_p256dh: Option<String>,
+    pub push_subscription_keys_auth: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_pass.rs b/lib/model/users/user_pass.rs
new file mode 100644
index 0000000..961d770
--- /dev/null
+++ b/lib/model/users/user_pass.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserPasswordModel {
+    pub user: Uuid,
+    pub hash: String,
+    pub salt: String,
+    pub is_active: bool,
+    pub reason: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_passreset.rs b/lib/model/users/user_passreset.rs
new file mode 100644
index 0000000..96951c8
--- /dev/null
+++ b/lib/model/users/user_passreset.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserPasswordResetModel {
+    pub token: String,
+    pub user: Uuid,
+    pub expires_at: DateTime<Utc>,
+    pub used: bool,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_privacy.rs b/lib/model/users/user_privacy.rs
new file mode 100644
index 0000000..a278029
--- /dev/null
+++ b/lib/model/users/user_privacy.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserPrivacyModel {
+    pub user: Uuid,
+    pub profile_visibility: String,
+    pub email_visibility: String,
+    pub activity_visibility: String,
+    pub allow_search_indexing: bool,
+    pub allow_direct_messages: bool,
+    pub show_online_status: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_profile.rs b/lib/model/users/user_profile.rs
new file mode 100644
index 0000000..3805203
--- /dev/null
+++ b/lib/model/users/user_profile.rs
@@ -0,0 +1,15 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserProfileModel {
+    pub user: Uuid,
+    pub language: String,
+    pub theme: String,
+    pub timezone: String,
+
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_session.rs b/lib/model/users/user_session.rs
new file mode 100644
index 0000000..53cd1c6
--- /dev/null
+++ b/lib/model/users/user_session.rs
@@ -0,0 +1,19 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserSessionModel {
+    pub id: Uuid,
+    pub user: Uuid,
+    pub token_hash: String,
+    pub device_name: Option<String>,
+    pub user_agent: Option<String>,
+    pub ip_address: Option<String>,
+    pub last_seen_at: Option<DateTime<Utc>>,
+    pub expires_at: DateTime<Utc>,
+    pub is_revoked: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_ssh_key.rs b/lib/model/users/user_ssh_key.rs
new file mode 100644
index 0000000..7efab54
--- /dev/null
+++ b/lib/model/users/user_ssh_key.rs
@@ -0,0 +1,21 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserSshKeyModel {
+    pub id: i64,
+    pub user: Uuid,
+    pub title: String,
+    pub public_key: String,
+    pub fingerprint: String,
+    pub key_type: String,
+    pub key_bits: Option<i32>,
+    pub is_verified: bool,
+    pub last_used_at: Option<DateTime<Utc>>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub is_revoked: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/users/user_token.rs b/lib/model/users/user_token.rs
new file mode 100644
index 0000000..a7c580d
--- /dev/null
+++ b/lib/model/users/user_token.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct UserTokenModel {
+    pub id: i64,
+    pub user: Uuid,
+    pub name: String,
+    pub token_hash: String,
+    pub scopes: String,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub is_revoked: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/workspace/mod.rs b/lib/model/workspace/mod.rs
new file mode 100644
index 0000000..92dbd87
--- /dev/null
+++ b/lib/model/workspace/mod.rs
@@ -0,0 +1,19 @@
+pub mod wk_apply_join;
+pub mod wk_billing;
+pub mod wk_gp_member;
+pub mod wk_gp_role;
+pub mod wk_group;
+pub mod wk_history_name;
+pub mod wk_join_approval;
+pub mod wk_join_strategy;
+pub mod wk_member;
+pub mod workspace;
+pub use wk_apply_join::WkApplyJoinModel;
+pub use wk_billing::WkBillingModel;
+pub use wk_gp_role::WkGpRoleModel;
+pub use wk_group::WkGroupModel;
+pub use wk_history_name::WkHistoryNameModel;
+pub use wk_join_approval::WkJoinApprovalModel;
+pub use wk_join_strategy::WkJoinStrategyModel;
+pub use wk_member::WkMemberModel;
+pub use workspace::WorkspaceModel;
diff --git a/lib/model/workspace/wk_apply_join.rs b/lib/model/workspace/wk_apply_join.rs
new file mode 100644
index 0000000..0b3556a
--- /dev/null
+++ b/lib/model/workspace/wk_apply_join.rs
@@ -0,0 +1,17 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkApplyJoinModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub user: Uuid,
+    pub status: String,
+    pub question: Option<String>,
+    pub answer: Option<String>,
+    pub message: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/workspace/wk_billing.rs b/lib/model/workspace/wk_billing.rs
new file mode 100644
index 0000000..6b14874
--- /dev/null
+++ b/lib/model/workspace/wk_billing.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use rust_decimal::Decimal;
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkBillingModel {
+    pub wk: Uuid,
+    pub balance: Decimal,
+    pub total_supply: Decimal,
+    pub total_supply_usable: Decimal,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/workspace/wk_gp_member.rs b/lib/model/workspace/wk_gp_member.rs
new file mode 100644
index 0000000..15491cc
--- /dev/null
+++ b/lib/model/workspace/wk_gp_member.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkGpMemberModel {
+    pub user: Uuid,
+    pub gp: Uuid,
+    pub join_at: DateTime<Utc>,
+    pub leave_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/workspace/wk_gp_role.rs b/lib/model/workspace/wk_gp_role.rs
new file mode 100644
index 0000000..87c3af3
--- /dev/null
+++ b/lib/model/workspace/wk_gp_role.rs
@@ -0,0 +1,18 @@
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkGpRoleModel {
+    pub wk: Uuid,
+    pub gp: Uuid,
+    pub repo_read: bool,
+    pub repo_write: bool,
+    pub channel_read: bool,
+    pub channel_write: bool,
+    pub ai_read: bool,
+    pub ai_write: bool,
+    pub pr_review: bool,
+    pub issues_ass: bool,
+    pub log_view: bool,
+}
diff --git a/lib/model/workspace/wk_group.rs b/lib/model/workspace/wk_group.rs
new file mode 100644
index 0000000..652e27c
--- /dev/null
+++ b/lib/model/workspace/wk_group.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkGroupModel {
+    pub id: Uuid,
+    pub name: String,
+    pub wk: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub avatar_url: Option<String>,
+    pub is_deleted: bool,
+}
diff --git a/lib/model/workspace/wk_history_name.rs b/lib/model/workspace/wk_history_name.rs
new file mode 100644
index 0000000..091b034
--- /dev/null
+++ b/lib/model/workspace/wk_history_name.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkHistoryNameModel {
+    pub id: Uuid,
+    pub wk: Uuid,
+    pub name: String,
+    pub changed_by: Uuid,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/workspace/wk_join_approval.rs b/lib/model/workspace/wk_join_approval.rs
new file mode 100644
index 0000000..67cb57a
--- /dev/null
+++ b/lib/model/workspace/wk_join_approval.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkJoinApprovalModel {
+    pub id: Uuid,
+    pub apply: Uuid,
+    pub wk: Uuid,
+    pub user: Uuid,
+    pub approver: Uuid,
+    pub approved: bool,
+    pub reason: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/model/workspace/wk_join_strategy.rs b/lib/model/workspace/wk_join_strategy.rs
new file mode 100644
index 0000000..dab260e
--- /dev/null
+++ b/lib/model/workspace/wk_join_strategy.rs
@@ -0,0 +1,16 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkJoinStrategyModel {
+    pub wk: Uuid,
+    pub require_approval: bool,
+    pub require_question: bool,
+    pub question: Option<String>,
+    pub answer: Option<String>,
+    pub enabled: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/lib/model/workspace/wk_member.rs b/lib/model/workspace/wk_member.rs
new file mode 100644
index 0000000..882c134
--- /dev/null
+++ b/lib/model/workspace/wk_member.rs
@@ -0,0 +1,14 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WkMemberModel {
+    pub wk: Uuid,
+    pub user: Uuid,
+    pub owner: bool,
+    pub admin: bool,
+    pub join_at: DateTime<Utc>,
+    pub leave_at: Option<DateTime<Utc>>,
+}
diff --git a/lib/model/workspace/workspace.rs b/lib/model/workspace/workspace.rs
new file mode 100644
index 0000000..dffd347
--- /dev/null
+++ b/lib/model/workspace/workspace.rs
@@ -0,0 +1,13 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, FromRow)]
+pub struct WorkspaceModel {
+    pub id: Uuid,
+    pub name: String,
+    pub description: String,
+    pub avatar_url: String,
+    pub created_at: DateTime<Utc>,
+}
diff --git a/lib/parsefile/Cargo.toml b/lib/parsefile/Cargo.toml
new file mode 100644
index 0000000..b80aa26
--- /dev/null
+++ b/lib/parsefile/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "parsefile"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[dependencies]
+serde = { workspace = true, features = ["derive"] }
+serde_yaml = { workspace = true }
+thiserror = { workspace = true }
+indexmap = { workspace = true, features = ["serde"] }
+
+[lints]
+workspace = true
diff --git a/lib/parsefile/ep.pipeline.yaml b/lib/parsefile/ep.pipeline.yaml
new file mode 100644
index 0000000..84be346
--- /dev/null
+++ b/lib/parsefile/ep.pipeline.yaml
@@ -0,0 +1,75 @@
+version: "1"
+
+name: "container-ci"
+
+run_on:
+  push:
+    branches:
+      - main
+      - "release/*"
+    tags:
+      - "v*"
+  pull_request:
+    branches:
+      - main
+      - "feature/*"
+
+jobs:
+  test:
+    stage: verify
+    runtime:
+      type: container
+      image: "node:20-bookworm"
+    runner_labels:
+      - linux
+      - container
+    steps:
+      - name: "Checkout"
+        task: "source.checkout"
+      - name: "Test"
+        command: "pnpm test"
+
+  build:
+    stage: package
+    depends_on:
+      - test
+    runtime:
+      type: container
+      image: "node:20-bookworm"
+    steps:
+      - name: "Checkout"
+        task: "source.checkout"
+      - name: "Build"
+        command: "pnpm build"
+      - name: "Upload dist"
+        task: "artifact.upload"
+        params:
+          name: "dist"
+          paths:
+            - "dist/**"
+
+  image:
+    stage: package
+    depends_on:
+      - build
+    runtime:
+      type: container
+      image: "docker:27-cli"
+    runner_labels:
+      - linux
+      - docker
+    steps:
+      - name: "Checkout"
+        task: "source.checkout"
+      - name: "Download dist"
+        task: "artifact.download"
+        params:
+          name: "dist"
+          path: "dist"
+      - name: "Build image"
+        task: "container.build"
+        params:
+          dockerfile: "Dockerfile"
+          context: "."
+          tags:
+            - "registry.example.com/app:${commit.sha}"
\ No newline at end of file
diff --git a/lib/parsefile/src/error.rs b/lib/parsefile/src/error.rs
new file mode 100644
index 0000000..8499fca
--- /dev/null
+++ b/lib/parsefile/src/error.rs
@@ -0,0 +1,23 @@
+#[derive(Debug, thiserror::Error)]
+pub enum ParseError {
+    #[error("failed to read file: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("failed to parse YAML: {0}")]
+    Yaml(#[from] serde_yaml::Error),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum ValidationError {
+    #[error("step '{step}' in job '{job}' has neither task nor command")]
+    EmptyStep { job: String, step: String },
+    #[error("dependency error: {0}")]
+    Dependency(#[from] DependencyError),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum DependencyError {
+    #[error("job '{job}' depends_on '{dependency}' which does not exist")]
+    UnknownReference { job: String, dependency: String },
+    #[error("circular dependency detected: {chain}")]
+    CircularDependency { chain: String },
+}
diff --git a/lib/parsefile/src/lib.rs b/lib/parsefile/src/lib.rs
new file mode 100644
index 0000000..976ee04
--- /dev/null
+++ b/lib/parsefile/src/lib.rs
@@ -0,0 +1,411 @@
+mod error;
+mod matcher;
+mod model;
+
+use std::path::Path;
+
+pub use error::{DependencyError, ParseError, ValidationError};
+pub use model::{
+    BranchPattern, Job, Pipeline, PipelineVersion, PullRequestTrigger,
+    PushTrigger, RunOn, Runtime, RuntimeType, Step, StepKind, StepParam,
+    TriggerEvent,
+};
+
+pub fn parse_file(path: &Path) -> Result<Pipeline, ParseError> {
+    let content = std::fs::read_to_string(path)?;
+    parse_from_str(&content)
+}
+
+pub fn parse_from_str(content: &str) -> Result<Pipeline, ParseError> {
+    let pipeline: Pipeline = serde_yaml::from_str(content)?;
+    Ok(pipeline)
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use super::*;
+
+    fn sample_pipeline_path() -> PathBuf {
+        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ep.pipeline.yaml")
+    }
+
+    #[test]
+    fn parse_sample_pipeline() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+
+        assert_eq!(pipeline.version, PipelineVersion::V1);
+        assert_eq!(pipeline.name, "container-ci");
+        assert_eq!(pipeline.jobs.len(), 3);
+    }
+
+    #[test]
+    fn parse_test_job() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        let test_job = &pipeline.jobs["test"];
+
+        assert_eq!(test_job.stage, "verify");
+        assert!(test_job.depends_on.is_empty());
+        assert_eq!(test_job.runtime.runtime_type, RuntimeType::Container);
+        assert_eq!(test_job.runtime.image, "node:20-bookworm");
+        assert_eq!(test_job.runner_labels, vec!["linux", "container"]);
+        assert_eq!(test_job.steps.len(), 2);
+
+        let checkout = &test_job.steps[0];
+        assert_eq!(checkout.name, "Checkout");
+        assert_eq!(checkout.kind(), Some(StepKind::Task));
+        assert_eq!(checkout.task, Some("source.checkout".to_string()));
+
+        let test_step = &test_job.steps[1];
+        assert_eq!(test_step.name, "Test");
+        assert_eq!(test_step.kind(), Some(StepKind::Command));
+        assert_eq!(test_step.command, Some("pnpm test".to_string()));
+    }
+
+    #[test]
+    fn parse_build_job_with_params() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        let build_job = &pipeline.jobs["build"];
+
+        assert_eq!(build_job.stage, "package");
+        assert_eq!(build_job.depends_on, vec!["test"]);
+
+        let upload_step = &build_job.steps[2];
+        assert_eq!(upload_step.name, "Upload dist");
+        assert_eq!(upload_step.kind(), Some(StepKind::Task));
+        assert_eq!(upload_step.task, Some("artifact.upload".to_string()));
+        assert_eq!(upload_step.params.get("name").unwrap().as_string(), "dist");
+        assert_eq!(
+            upload_step.params.get("paths").unwrap().as_list(),
+            &["dist/**".to_string()]
+        );
+    }
+
+    #[test]
+    fn parse_image_job() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        let image_job = &pipeline.jobs["image"];
+
+        assert_eq!(image_job.stage, "package");
+        assert_eq!(image_job.depends_on, vec!["build"]);
+        assert_eq!(image_job.runtime.runtime_type, RuntimeType::Container);
+        assert_eq!(image_job.runtime.image, "docker:27-cli");
+        assert_eq!(image_job.runner_labels, vec!["linux", "docker"]);
+
+        let build_image_step = &image_job.steps[2];
+        assert_eq!(build_image_step.name, "Build image");
+        assert_eq!(build_image_step.kind(), Some(StepKind::Task));
+        assert_eq!(
+            build_image_step
+                .params
+                .get("dockerfile")
+                .unwrap()
+                .as_string(),
+            "Dockerfile"
+        );
+        assert_eq!(
+            build_image_step.params.get("tags").unwrap().as_list(),
+            &["registry.example.com/app:${commit.sha}".to_string()]
+        );
+    }
+
+    #[test]
+    fn parse_run_on() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        let run_on = pipeline.run_on.as_ref().unwrap();
+
+        let push = run_on.push.as_ref().unwrap();
+        assert_eq!(push.branches.len(), 2);
+        assert_eq!(push.branches[0].as_str(), "main");
+        assert_eq!(push.branches[1].as_str(), "release/*");
+        assert_eq!(push.tags.len(), 1);
+        assert_eq!(push.tags[0].as_str(), "v*");
+
+        let pr = run_on.pull_request.as_ref().unwrap();
+        assert_eq!(pr.branches.len(), 2);
+        assert_eq!(pr.branches[0].as_str(), "main");
+        assert_eq!(pr.branches[1].as_str(), "feature/*");
+    }
+
+    #[test]
+    fn stages_and_jobs_by_stage() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+
+        let stages = pipeline.stages();
+        assert_eq!(stages, vec!["verify", "package"]);
+
+        let verify_jobs = pipeline.jobs_by_stage("verify");
+        assert_eq!(verify_jobs.len(), 1);
+
+        let package_jobs = pipeline.jobs_by_stage("package");
+        assert_eq!(package_jobs.len(), 2);
+    }
+
+    #[test]
+    fn execution_order() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        let order = pipeline.execution_order().unwrap();
+
+        let test_idx = order.iter().position(|j| j == "test").unwrap();
+        let build_idx = order.iter().position(|j| j == "build").unwrap();
+        let image_idx = order.iter().position(|j| j == "image").unwrap();
+        assert!(test_idx < build_idx);
+        assert!(build_idx < image_idx);
+    }
+
+    #[test]
+    fn validate_sample_pipeline() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(pipeline.validate().is_ok());
+    }
+
+    #[test]
+    fn validation_empty_step() {
+        let yaml = r#"
+version: "1"
+name: "bad-pipeline"
+jobs:
+  build:
+    stage: package
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "NoAction"
+"#;
+        let pipeline = parse_from_str(yaml).unwrap();
+        let err = pipeline.validate().unwrap_err();
+        assert!(matches!(err, ValidationError::EmptyStep { .. }));
+    }
+
+    #[test]
+    fn validation_unknown_dependency() {
+        let yaml = r#"
+version: "1"
+name: "bad-pipeline"
+jobs:
+  build:
+    stage: package
+    depends_on:
+      - nonexistent
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "Build"
+        command: "echo hi"
+"#;
+        let pipeline = parse_from_str(yaml).unwrap();
+        let err = pipeline.execution_order().unwrap_err();
+        assert!(matches!(err, DependencyError::UnknownReference { .. }));
+    }
+
+    #[test]
+    fn validation_circular_dependency() {
+        let yaml = r#"
+version: "1"
+name: "bad-pipeline"
+jobs:
+  a:
+    stage: build
+    depends_on:
+      - b
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "A"
+        command: "echo a"
+  b:
+    stage: build
+    depends_on:
+      - a
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "B"
+        command: "echo b"
+"#;
+        let pipeline = parse_from_str(yaml).unwrap();
+        let err = pipeline.execution_order().unwrap_err();
+        assert!(matches!(err, DependencyError::CircularDependency { .. }));
+    }
+
+    #[test]
+    fn parse_from_str_unknown_version() {
+        let yaml = r#"
+version: "99"
+name: "test"
+jobs: {}
+"#;
+        assert!(parse_from_str(yaml).is_err());
+    }
+
+    #[test]
+    fn parse_from_str_unknown_runtime_type() {
+        let yaml = r#"
+version: "1"
+name: "test"
+jobs:
+  build:
+    stage: package
+    runtime:
+      type: unknown
+      image: "node:20"
+    steps:
+      - name: "Build"
+        command: "echo hi"
+"#;
+        assert!(parse_from_str(yaml).is_err());
+    }
+
+    #[test]
+    fn should_run_push_main() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(pipeline.should_run(&TriggerEvent::PushBranch("main".into())));
+    }
+
+    #[test]
+    fn should_run_push_release_branch() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(
+            pipeline
+                .should_run(&TriggerEvent::PushBranch("release/1.0".into()))
+        );
+    }
+
+    #[test]
+    fn should_run_push_feature_branch_rejected() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(
+            !pipeline
+                .should_run(&TriggerEvent::PushBranch("feature/login".into()))
+        );
+    }
+
+    #[test]
+    fn should_run_push_tag() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(pipeline.should_run(&TriggerEvent::PushTag("v1.0.0".into())));
+        assert!(!pipeline.should_run(&TriggerEvent::PushTag("1.0.0".into())));
+    }
+
+    #[test]
+    fn should_run_pull_request_main() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(pipeline.should_run(&TriggerEvent::PullRequest {
+            target: "main".into()
+        }));
+    }
+
+    #[test]
+    fn should_run_pull_request_feature() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(pipeline.should_run(&TriggerEvent::PullRequest {
+            target: "feature/login".into()
+        }));
+    }
+
+    #[test]
+    fn should_run_pull_request_develop_rejected() {
+        let pipeline = parse_file(&sample_pipeline_path()).unwrap();
+        assert!(!pipeline.should_run(&TriggerEvent::PullRequest {
+            target: "develop".into()
+        }));
+    }
+
+    #[test]
+    fn should_run_no_run_on_always_true() {
+        let yaml = r#"
+version: "1"
+name: "always-run"
+jobs:
+  build:
+    stage: package
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "Build"
+        command: "echo hi"
+"#;
+        let pipeline = parse_from_str(yaml).unwrap();
+        assert!(
+            pipeline.should_run(&TriggerEvent::PushBranch("anything".into()))
+        );
+        assert!(pipeline.should_run(&TriggerEvent::PullRequest {
+            target: "anything".into()
+        }));
+    }
+
+    #[test]
+    fn should_run_push_with_empty_branches_matches_all() {
+        let yaml = r#"
+version: "1"
+name: "push-any-branch"
+run_on:
+  push: {}
+jobs:
+  build:
+    stage: package
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "Build"
+        command: "echo hi"
+"#;
+        let pipeline = parse_from_str(yaml).unwrap();
+        assert!(
+            pipeline.should_run(&TriggerEvent::PushBranch("anything".into()))
+        );
+        assert!(pipeline.should_run(&TriggerEvent::PushTag("v1".into())));
+    }
+
+    #[test]
+    fn should_run_push_only_no_pull_request() {
+        let yaml = r#"
+version: "1"
+name: "push-only"
+run_on:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    stage: package
+    runtime:
+      type: container
+      image: "node:20"
+    steps:
+      - name: "Build"
+        command: "echo hi"
+"#;
+        let pipeline = parse_from_str(yaml).unwrap();
+        assert!(pipeline.should_run(&TriggerEvent::PushBranch("main".into())));
+        assert!(!pipeline.should_run(&TriggerEvent::PullRequest {
+            target: "main".into()
+        }));
+    }
+
+    #[test]
+    fn branch_pattern_exact_and_glob() {
+        let exact = BranchPattern::new("main");
+        assert!(!exact.is_pattern());
+        assert!(exact.matches("main"));
+        assert!(!exact.matches("develop"));
+
+        let glob = BranchPattern::new("release/*");
+        assert!(glob.is_pattern());
+        assert!(glob.matches("release/1.0"));
+        assert!(!glob.matches("release/1.0/fix"));
+        assert!(!glob.matches("main"));
+
+        let deep = BranchPattern::new("feature/**");
+        assert!(deep.is_pattern());
+        assert!(deep.matches("feature/login"));
+        assert!(deep.matches("feature/login/subtask"));
+    }
+}
diff --git a/lib/parsefile/src/matcher.rs b/lib/parsefile/src/matcher.rs
new file mode 100644
index 0000000..6aee9cd
--- /dev/null
+++ b/lib/parsefile/src/matcher.rs
@@ -0,0 +1,93 @@
+pub fn glob_match(pattern: &str, text: &str) -> bool {
+    match_impl(pattern.as_bytes(), text.as_bytes())
+}
+
+fn match_impl(pattern: &[u8], text: &[u8]) -> bool {
+    if pattern.is_empty() {
+        return text.is_empty();
+    }
+    if pattern.len() >= 2 && pattern[0] == b'*' && pattern[1] == b'*' {
+        let rest = skip_double_star_slash(pattern);
+        for i in 0..=text.len() {
+            if match_impl(rest, &text[i..]) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if pattern[0] == b'*' {
+        let rest = &pattern[1..];
+        for i in 0..=text.len() {
+            if i > 0 && text[i - 1] == b'/' {
+                break;
+            }
+            if match_impl(rest, &text[i..]) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    if text.is_empty() {
+        return false;
+    }
+    if pattern[0] == b'?' {
+        if text[0] == b'/' {
+            return false;
+        }
+        return match_impl(&pattern[1..], &text[1..]);
+    }
+    if pattern[0] == text[0] {
+        return match_impl(&pattern[1..], &text[1..]);
+    }
+
+    false
+}
+fn skip_double_star_slash(pattern: &[u8]) -> &[u8] {
+    let rest = &pattern[2..];
+    if rest.first() == Some(&b'/') {
+        &rest[1..]
+    } else {
+        rest
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn exact_match() {
+        assert!(glob_match("main", "main"));
+        assert!(!glob_match("main", "develop"));
+    }
+
+    #[test]
+    fn single_star_matches_segment() {
+        assert!(glob_match("featurerelease", "release"));
+        assert!(glob_match("**/release", "a/b/c/release"));
+    }
+
+    #[test]
+    fn question_mark() {
+        assert!(glob_match("v?", "v1"));
+        assert!(glob_match("v?", "vA"));
+        assert!(!glob_match("v?", "v12"));
+        assert!(!glob_match("v?", "v/"));
+    }
+
+    #[test]
+    fn tag_patterns() {
+        assert!(glob_match("v*", "v1.0.0"));
+        assert!(glob_match("v*", "v2"));
+        assert!(!glob_match("v*", "2.0.0"));
+        assert!(glob_match("release-*", "release-2024"));
+    }
+
+    #[test]
+    fn star_at_start() {
+        assert!(glob_match("*-staging", "dev-staging"));
+        assert!(glob_match("*-staging", "test-staging"));
+        assert!(!glob_match("*-staging", "dev/staging"));
+    }
+}
diff --git a/lib/parsefile/src/model.rs b/lib/parsefile/src/model.rs
new file mode 100644
index 0000000..2c3dd67
--- /dev/null
+++ b/lib/parsefile/src/model.rs
@@ -0,0 +1,280 @@
+use std::collections::HashMap;
+
+use indexmap::IndexMap;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    error::{DependencyError, ValidationError},
+    matcher::glob_match,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PipelineVersion {
+    #[serde(rename = "1")]
+    V1,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum RuntimeType {
+    #[serde(rename = "container")]
+    Container,
+    #[serde(rename = "host")]
+    Host,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum StepKind {
+    Task,
+    Command,
+}
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TriggerEvent {
+    PushBranch(String),
+    PushTag(String),
+    PullRequest { target: String },
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RunOn {
+    #[serde(default)]
+    pub push: Option<PushTrigger>,
+    #[serde(default)]
+    pub pull_request: Option<PullRequestTrigger>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PushTrigger {
+    #[serde(default)]
+    pub branches: Vec<BranchPattern>,
+    #[serde(default)]
+    pub tags: Vec<BranchPattern>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PullRequestTrigger {
+    #[serde(default)]
+    pub branches: Vec<BranchPattern>,
+}
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BranchPattern(String);
+
+impl BranchPattern {
+    pub fn new(pattern: impl Into<String>) -> Self {
+        Self(pattern.into())
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    pub fn is_pattern(&self) -> bool {
+        self.0.contains('*') || self.0.contains('?')
+    }
+    pub fn matches(&self, name: &str) -> bool {
+        if !self.is_pattern() {
+            self.0 == name
+        } else {
+            glob_match(&self.0, name)
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Pipeline {
+    pub version: PipelineVersion,
+    pub name: String,
+    #[serde(default)]
+    pub run_on: Option<RunOn>,
+    pub jobs: IndexMap<String, Job>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Job {
+    pub stage: String,
+    #[serde(default)]
+    pub depends_on: Vec<String>,
+    pub runtime: Runtime,
+    #[serde(default)]
+    pub runner_labels: Vec<String>,
+    pub steps: Vec<Step>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Runtime {
+    #[serde(rename = "type")]
+    pub runtime_type: RuntimeType,
+    pub image: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Step {
+    pub name: String,
+    #[serde(default)]
+    pub task: Option<String>,
+    #[serde(default)]
+    pub command: Option<String>,
+    #[serde(default)]
+    pub params: IndexMap<String, StepParam>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum StepParam {
+    String(String),
+    List(Vec<String>),
+}
+
+impl Step {
+    pub fn kind(&self) -> Option<StepKind> {
+        if self.task.is_some() {
+            Some(StepKind::Task)
+        } else if self.command.is_some() {
+            Some(StepKind::Command)
+        } else {
+            None
+        }
+    }
+}
+
+impl StepParam {
+    pub fn as_string(&self) -> &str {
+        match self {
+            StepParam::String(s) => s,
+            StepParam::List(_) => {
+                panic!("StepParam::as_string called on a List variant")
+            }
+        }
+    }
+
+    pub fn as_list(&self) -> &[String] {
+        match self {
+            StepParam::String(_) => {
+                panic!("StepParam::as_list called on a String variant")
+            }
+            StepParam::List(v) => v,
+        }
+    }
+}
+
+impl Pipeline {
+    pub fn jobs_by_stage(&self, stage: &str) -> Vec<&Job> {
+        self.jobs.values().filter(|j| j.stage == stage).collect()
+    }
+
+    pub fn stages(&self) -> Vec<&str> {
+        let mut seen: Vec<&str> = Vec::new();
+        for job in self.jobs.values() {
+            if !seen.contains(&job.stage.as_str()) {
+                seen.push(&job.stage);
+            }
+        }
+        seen
+    }
+    pub fn should_run(&self, event: &TriggerEvent) -> bool {
+        let run_on = match &self.run_on {
+            None => return true,
+            Some(r) => r,
+        };
+
+        match event {
+            TriggerEvent::PushBranch(branch) => {
+                run_on.push.as_ref().map_or(false, |p| {
+                    if p.branches.is_empty() {
+                        true
+                    } else {
+                        p.branches.iter().any(|bp| bp.matches(branch))
+                    }
+                })
+            }
+            TriggerEvent::PushTag(tag) => {
+                run_on.push.as_ref().map_or(false, |p| {
+                    if p.tags.is_empty() {
+                        true
+                    } else {
+                        p.tags.iter().any(|tp| tp.matches(tag))
+                    }
+                })
+            }
+            TriggerEvent::PullRequest { target } => {
+                run_on.pull_request.as_ref().map_or(false, |pr| {
+                    if pr.branches.is_empty() {
+                        true
+                    } else {
+                        pr.branches.iter().any(|bp| bp.matches(target))
+                    }
+                })
+            }
+        }
+    }
+
+    pub fn execution_order(&self) -> Result<Vec<String>, DependencyError> {
+        let mut in_degree: HashMap<&str, usize> = HashMap::new();
+        let mut graph: HashMap<&str, Vec<&str>> = HashMap::new();
+
+        for name in self.jobs.keys() {
+            in_degree.insert(name, 0);
+            graph.insert(name, Vec::new());
+        }
+
+        for (name, job) in &self.jobs {
+            for dep in &job.depends_on {
+                if !self.jobs.contains_key(dep) {
+                    return Err(DependencyError::UnknownReference {
+                        job: name.clone(),
+                        dependency: dep.clone(),
+                    });
+                }
+                graph.get_mut(dep.as_str()).unwrap().push(name);
+                *in_degree.get_mut(name.as_str()).unwrap() += 1;
+            }
+        }
+
+        let mut queue: Vec<&str> = in_degree
+            .iter()
+            .filter(|(_, deg)| **deg == 0)
+            .map(|(name, _)| *name)
+            .collect();
+        queue.sort();
+
+        let mut order: Vec<String> = Vec::new();
+        while let Some(node) = queue.pop() {
+            order.push(node.to_string());
+            for &neighbor in &graph[node] {
+                let deg = in_degree.get_mut(neighbor).unwrap();
+                *deg -= 1;
+                if *deg == 0 {
+                    queue.push(neighbor);
+                    queue.sort();
+                }
+            }
+        }
+
+        if order.len() != self.jobs.len() {
+            let cycle_nodes: Vec<String> = self
+                .jobs
+                .keys()
+                .filter(|k| !order.contains(k))
+                .cloned()
+                .collect();
+            return Err(DependencyError::CircularDependency {
+                chain: cycle_nodes.join(" -> "),
+            });
+        }
+
+        Ok(order)
+    }
+
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        for (name, job) in &self.jobs {
+            for step in &job.steps {
+                if step.kind().is_none() {
+                    return Err(ValidationError::EmptyStep {
+                        job: name.clone(),
+                        step: step.name.clone(),
+                    });
+                }
+            }
+        }
+        self.execution_order()?;
+        Ok(())
+    }
+}
diff --git a/lib/queue/Cargo.toml b/lib/queue/Cargo.toml
new file mode 100644
index 0000000..6c78440
--- /dev/null
+++ b/lib/queue/Cargo.toml
@@ -0,0 +1,30 @@
+[package]
+name = "queue"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "queue"
+[dependencies]
+async-nats = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+tracing = { workspace = true }
+anyhow = { workspace = true }
+async-trait = { workspace = true }
+config = { workspace = true }
+futures-util = { workspace = true }
+
+[lints]
+workspace = true
diff --git a/lib/queue/consumer.rs b/lib/queue/consumer.rs
new file mode 100644
index 0000000..77fa31b
--- /dev/null
+++ b/lib/queue/consumer.rs
@@ -0,0 +1,206 @@
+use std::{sync::Arc, time::Duration};
+
+use async_nats::{HeaderMap, jetstream};
+use config::AppConfig;
+use futures_util::StreamExt;
+use tracing::{error, info, warn};
+
+use crate::{
+    handler::{AckAction, MessageHandler},
+    producer::{NatsProducer, connect_jetstream, ensure_stream},
+};
+
+pub struct NatsConsumer {
+    stream: jetstream::stream::Stream,
+    producer: NatsProducer,
+    max_deliver: i64,
+    retry_delay_secs: u64,
+    durable_name: String,
+}
+
+impl NatsConsumer {
+    pub async fn new(
+        config: &AppConfig,
+        group_id: &str,
+    ) -> anyhow::Result<Self> {
+        let jetstream = connect_jetstream(config).await?;
+        let stream = ensure_stream(config, &jetstream).await?;
+        let producer = NatsProducer::new(config).await?;
+
+        Ok(Self {
+            stream,
+            producer,
+            max_deliver: config.nats_max_deliver(),
+            retry_delay_secs: config.nats_retry_delay_secs(),
+            durable_name: durable_name(group_id),
+        })
+    }
+
+    pub async fn start_consuming<H>(
+        &self,
+        topics: &[&str],
+        handler: H,
+    ) -> anyhow::Result<()>
+    where
+        H: MessageHandler + 'static,
+    {
+        let topics_owned: Vec<String> =
+            topics.iter().map(|topic| topic.to_string()).collect();
+
+        let consumer = self
+            .stream
+            .get_or_create_consumer(
+                &self.durable_name,
+                jetstream::consumer::pull::Config {
+                    durable_name: Some(self.durable_name.clone()),
+                    ack_wait: Duration::from_secs(self.retry_delay_secs),
+                    max_deliver: self.max_deliver,
+                    filter_subjects: topics_owned.clone(),
+                    ..Default::default()
+                },
+            )
+            .await?;
+
+        info!("NATS consumer started subscribing to: {:?}", topics_owned);
+
+        let producer = self.producer.clone();
+        let max_deliver = self.max_deliver;
+        let retry_delay_secs = self.retry_delay_secs;
+        let handler = Arc::new(handler);
+
+        tokio::spawn(async move {
+            let messages = consumer.messages().await;
+            let mut messages = match messages {
+                Ok(messages) => messages,
+                Err(error) => {
+                    error!(
+                        "NATS error while opening consumer stream: {:?}",
+                        error
+                    );
+                    return;
+                }
+            };
+
+            while let Some(message_result) = messages.next().await {
+                match message_result {
+                    Ok(message) => {
+                        handle_message(
+                            &producer,
+                            max_deliver,
+                            retry_delay_secs,
+                            handler.as_ref(),
+                            message,
+                        )
+                        .await;
+                    }
+                    Err(error) => {
+                        error!("NATS error while consuming: {:?}", error);
+                    }
+                }
+            }
+        });
+
+        Ok(())
+    }
+}
+
+async fn handle_message<H>(
+    producer: &NatsProducer,
+    max_deliver: i64,
+    retry_delay_secs: u64,
+    handler: &H,
+    message: jetstream::Message,
+) where
+    H: MessageHandler + ?Sized,
+{
+    let subject = message.subject.to_string();
+    let payload = message.payload.clone();
+    let delivered = message.info().map(|info| info.delivered).unwrap_or(1);
+
+    match handler.handle(&subject, &payload).await {
+        AckAction::Ack => ack_message(&message, &subject, "message").await,
+        AckAction::Nack => {
+            if let Err(error) = handle_nack(
+                producer,
+                &message,
+                &subject,
+                &payload,
+                delivered,
+                max_deliver,
+                retry_delay_secs,
+            )
+            .await
+            {
+                error!(
+                    "Failed to route NACKed message from subject {}: {:?}",
+                    subject, error
+                );
+            }
+        }
+    }
+}
+
+async fn handle_nack(
+    producer: &NatsProducer,
+    message: &jetstream::Message,
+    subject: &str,
+    payload: &[u8],
+    delivered: i64,
+    max_deliver: i64,
+    retry_delay_secs: u64,
+) -> anyhow::Result<()> {
+    if delivered < max_deliver {
+        warn!(
+            "Message in subject {} failed (NACK). Retrying delivery {}/{} in {} seconds",
+            subject, delivered, max_deliver, retry_delay_secs
+        );
+        message
+            .ack_with(jetstream::AckKind::Nak(Some(Duration::from_secs(
+                retry_delay_secs,
+            ))))
+            .await
+            .map_err(|error| {
+                anyhow::anyhow!("failed to nack message: {error}")
+            })?;
+        return Ok(());
+    }
+
+    let dlq_subject = format!("{subject}.dlq");
+    error!(
+        "Message in subject {} exceeded max deliver attempts ({}). Routing to DLQ: {}",
+        subject, max_deliver, dlq_subject
+    );
+
+    let mut headers = HeaderMap::new();
+    headers.append("x-original-subject", subject);
+    headers.append("x-delivered-count", delivered.to_string());
+    producer
+        .send_raw(&dlq_subject, "", payload, Some(headers))
+        .await
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to send DLQ message to {dlq_subject}: {error}"
+            )
+        })?;
+    message.ack().await.map_err(|error| {
+        anyhow::anyhow!("failed to ack DLQ message: {error}")
+    })?;
+    Ok(())
+}
+
+async fn ack_message(
+    message: &jetstream::Message,
+    subject: &str,
+    description: &str,
+) {
+    if let Err(error) = message.ack().await {
+        error!(
+            "Failed to ack {} in subject {}: {:?}",
+            description, subject, error
+        );
+    }
+}
+
+fn durable_name(name: &str) -> String {
+    name.replace('.', "-")
+}
diff --git a/lib/queue/handler.rs b/lib/queue/handler.rs
new file mode 100644
index 0000000..869c5a7
--- /dev/null
+++ b/lib/queue/handler.rs
@@ -0,0 +1,9 @@
+pub enum AckAction {
+    Ack,
+    Nack,
+}
+
+#[async_trait::async_trait]
+pub trait MessageHandler: Send + Sync {
+    async fn handle(&self, topic: &str, payload: &[u8]) -> AckAction;
+}
diff --git a/lib/queue/lib.rs b/lib/queue/lib.rs
new file mode 100644
index 0000000..1c57159
--- /dev/null
+++ b/lib/queue/lib.rs
@@ -0,0 +1,7 @@
+mod consumer;
+mod handler;
+mod producer;
+
+pub use consumer::NatsConsumer;
+pub use handler::{AckAction, MessageHandler};
+pub use producer::NatsProducer;
diff --git a/lib/queue/producer.rs b/lib/queue/producer.rs
new file mode 100644
index 0000000..6e770b9
--- /dev/null
+++ b/lib/queue/producer.rs
@@ -0,0 +1,90 @@
+use std::time::Duration;
+
+use async_nats::{HeaderMap, jetstream};
+use config::AppConfig;
+use serde::Serialize;
+
+#[derive(Clone)]
+pub struct NatsProducer {
+    jetstream: jetstream::Context,
+}
+
+impl NatsProducer {
+    pub async fn new(config: &AppConfig) -> anyhow::Result<Self> {
+        let jetstream = connect_jetstream(config).await?;
+        ensure_stream(config, &jetstream).await?;
+
+        Ok(Self { jetstream })
+    }
+
+    pub async fn send<T>(
+        &self,
+        subject: &str,
+        key: &str,
+        payload: &T,
+        headers: Option<HeaderMap>,
+    ) -> anyhow::Result<()>
+    where
+        T: Serialize + ?Sized,
+    {
+        let payload_bytes = serde_json::to_vec(payload)?;
+        self.send_raw(subject, key, &payload_bytes, headers).await
+    }
+
+    pub async fn send_raw(
+        &self,
+        subject: &str,
+        key: &str,
+        payload: &[u8],
+        headers: Option<HeaderMap>,
+    ) -> anyhow::Result<()> {
+        let mut headers = headers.unwrap_or_default();
+        if !key.is_empty() {
+            headers.append("x-message-key", key);
+        }
+
+        let subject = subject.to_string();
+        let publish = if headers.is_empty() {
+            self.jetstream
+                .publish(subject.clone(), payload.to_vec().into())
+                .await?
+        } else {
+            self.jetstream
+                .publish_with_headers(subject, headers, payload.to_vec().into())
+                .await?
+        };
+
+        tokio::time::timeout(Duration::from_secs(5), publish).await??;
+
+        Ok(())
+    }
+}
+
+pub(crate) async fn connect_jetstream(
+    config: &AppConfig,
+) -> anyhow::Result<jetstream::Context> {
+    let client = match config.nats_token() {
+        Some(token) if !token.is_empty() => {
+            async_nats::ConnectOptions::with_token(token)
+                .connect(config.nats_url())
+                .await?
+        }
+        _ => async_nats::connect(config.nats_url()).await?,
+    };
+
+    Ok(jetstream::new(client))
+}
+
+pub(crate) async fn ensure_stream(
+    config: &AppConfig,
+    jetstream: &jetstream::Context,
+) -> anyhow::Result<jetstream::stream::Stream> {
+    Ok(jetstream
+        .get_or_create_stream(jetstream::stream::Config {
+            name: config.nats_stream_name(),
+            subjects: config.nats_stream_subjects(),
+            max_age: Duration::from_secs(config.nats_max_age_secs()),
+            ..Default::default()
+        })
+        .await?)
+}
diff --git a/lib/service/Cargo.toml b/lib/service/Cargo.toml
new file mode 100644
index 0000000..892efcb
--- /dev/null
+++ b/lib/service/Cargo.toml
@@ -0,0 +1,59 @@
+[package]
+name = "service"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "service"
+[dependencies]
+db = { workspace = true }
+config = { workspace = true }
+cache = { workspace = true }
+queue = { workspace = true }
+email = { workspace = true }
+ai = { workspace = true }
+session = { workspace = true }
+storage = { workspace = true }
+model = { workspace = true }
+
+serde = { workspace = true, features = ["derive"]}
+utoipa = { workspace = true, features = ["chrono","uuid"] }
+hkdf = "0.13.0"
+rsa = "0.10.0-rc.18"
+rand_chacha = "0.10.0"
+sha2 = "0.11.0"
+chacha20poly1305 = "0.11.0-rc.3"
+base64 = "0.22.1"
+serde_json = "1.0.150"
+rand = "0.10.1"
+hex = "0.4.3"
+tracing = "0.1.44"
+sqlx = { workspace = true }
+captcha-rs = "0.5.0"
+argon2 = "0.6.0-rc.8"
+chrono = { workspace = true }
+uuid = { workspace = true, features = ["v4", "v7", "serde"] }
+rust_decimal = "1.42.0"
+hmac = "0.13.0"
+sha1 = "0.11.0"
+git = { workspace = true }
+tonic = { workspace = true, features = ["transport"] }
+comrak = { workspace = true }
+deadpool-redis = { workspace = true, features = ["cluster"] }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp"] }
+tokio = { workspace = true, features = ["full"] }
+tokio-util = { workspace = true }
+async-trait = { workspace = true }
+rig-core = { workspace = true }
+[lints]
+workspace = true
diff --git a/lib/service/agent/billing.rs b/lib/service/agent/billing.rs
new file mode 100644
index 0000000..cb7fc2c
--- /dev/null
+++ b/lib/service/agent/billing.rs
@@ -0,0 +1,316 @@
+use chrono::Utc;
+use db::sqlx::{self, types::Decimal};
+use rust_decimal::Decimal as RustDecimal;
+use uuid::Uuid;
+
+use super::types::{BillingRecord, BillingTarget, SessionContext};
+use crate::error::AppError;
+use crate::AppService;
+
+impl AppService {
+    pub(crate) async fn agent_calculate_cost(
+        &self,
+        model_version_id: Uuid,
+        input_tokens: i64,
+        output_tokens: i64,
+    ) -> Result<Option<(RustDecimal, String)>, AppError> {
+        let (input_price_per_million, output_price_per_million) =
+            self.agent_resolve_pricing(model_version_id).await?;
+
+        let input_price = match input_price_per_million {
+            Some(p) => p,
+            None => return Ok(None),
+        };
+
+        let output_price = match output_price_per_million {
+            Some(p) => p,
+            None => return Ok(None),
+        };
+
+        let million = RustDecimal::from(1_000_000u64);
+        let input_decimal = RustDecimal::from(input_tokens);
+        let output_decimal = RustDecimal::from(output_tokens);
+
+        let cost = (input_decimal * input_price / million)
+            + (output_decimal * output_price / million);
+        Ok(Some((cost, "USD".to_string())))
+    }
+    pub(crate) async fn agent_deduct_billing(
+        &self,
+        ctx: &SessionContext,
+        cost: RustDecimal,
+    ) -> Result<(), AppError> {
+        match ctx.billing_target {
+            BillingTarget::User => {
+                let user_id = ctx
+                    .user_id
+                    .ok_or_else(|| AppError::BadRequest("user billing target requires user_id".to_string()))?;
+                self.deduct_user_balance(user_id, cost).await
+            }
+            BillingTarget::Workspace => {
+                let wk_id = ctx
+                    .workspace_id
+                    .ok_or_else(|| AppError::BadRequest("workspace billing target requires workspace_id".to_string()))?;
+                self.deduct_workspace_balance(wk_id, cost).await
+            }
+        }
+    }
+    pub(crate) async fn agent_record_usage(
+        &self,
+        record: &BillingRecord,
+    ) -> Result<(), AppError> {
+        let cost_decimal: Option<Decimal> = record.cost.map(|c| c.into());
+
+        sqlx::query(
+            "INSERT INTO agent_token_usage \
+             (invocation, session, model_version, \
+              input_tokens, output_tokens, cached_input_tokens, \
+              cache_read_tokens, cache_write_tokens, reasoning_tokens, \
+              total_tokens, cost, currency, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)",
+        )
+        .bind(record.invocation_id)
+        .bind(record.session_id)
+        .bind(record.model_version_id)
+        .bind(record.input_tokens)
+        .bind(record.output_tokens)
+        .bind(record.cached_input_tokens)
+        .bind(record.cache_read_tokens)
+        .bind(record.cache_write_tokens)
+        .bind(record.reasoning_tokens)
+        .bind(record.total_tokens)
+        .bind(&cost_decimal)
+        .bind(&record.currency)
+        .bind(record.created_at)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+    pub(crate) async fn agent_record_invocation(
+        &self,
+        invocation_id: Uuid,
+        session_id: Uuid,
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        model_version_id: Uuid,
+        status: &str,
+        error: Option<&str>,
+    ) -> Result<(), AppError> {
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_model_invocation \
+             (id, session, conversation, message, model_version, status, error, \
+              started_at, finished_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)",
+        )
+        .bind(invocation_id)
+        .bind(session_id)
+        .bind(conversation_id)
+        .bind(message_id)
+        .bind(model_version_id)
+        .bind(status)
+        .bind(error)
+        .bind(now)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+    pub(crate) async fn agent_record_tool_call(
+        &self,
+        invocation_id: Uuid,
+        session_id: Uuid,
+        conversation_id: Option<Uuid>,
+        message_id: Option<Uuid>,
+        tool_call_id: &str,
+        tool_name: &str,
+        arguments: Option<&str>,
+        result: Option<&str>,
+        error: Option<&str>,
+        status: &str,
+        latency_ms: Option<i64>,
+    ) -> Result<(), AppError> {
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_tool_call_log \
+             (invocation, session, conversation, message, tool_call_id, \
+              tool_name, arguments, result, error, status, \
+              started_at, finished_at, latency_ms) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)",
+        )
+        .bind(invocation_id)
+        .bind(session_id)
+        .bind(conversation_id)
+        .bind(message_id)
+        .bind(tool_call_id)
+        .bind(tool_name)
+        .bind(arguments)
+        .bind(result)
+        .bind(error)
+        .bind(status)
+        .bind(now)
+        .bind(now)
+        .bind(latency_ms)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+}
+
+impl AppService {
+    async fn deduct_user_balance(
+        &self,
+        user_id: Uuid,
+        cost: RustDecimal,
+    ) -> Result<(), AppError> {
+        const MAX_RETRIES: u32 = 3;
+        for attempt in 0..MAX_RETRIES {
+            match self.try_deduct_user_balance(user_id, cost).await {
+                Ok(()) => return Ok(()),
+                Err(AppError::TxnError) if attempt < MAX_RETRIES - 1 => {
+                    let backoff_ms = 10 * (1 << attempt);
+                    tokio::time::sleep(tokio::time::Duration::from_millis(backoff_ms)).await;
+                    continue;
+                }
+                Err(e) => return Err(e),
+            }
+        }
+        Err(AppError::TxnError)
+    }
+
+    async fn try_deduct_user_balance(
+        &self,
+        user_id: Uuid,
+        cost: RustDecimal,
+    ) -> Result<(), AppError> {
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let current: Option<RustDecimal> = sqlx::query_scalar(
+            "SELECT balance FROM user_billing WHERE \"user\" = $1 FOR UPDATE",
+        )
+        .bind(user_id)
+        .fetch_optional(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let current = match current {
+            Some(balance) => balance,
+            None => {
+                let default_balance = RustDecimal::from(20);
+                let now = Utc::now();
+                sqlx::query(
+                    "INSERT INTO user_billing (\"user\", balance, created_at, updated_at) \
+                     VALUES ($1, $2, $3, $3)",
+                )
+                .bind(user_id)
+                .bind(&default_balance)
+                .bind(now)
+                .execute(&mut **txn.inner_mut())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+                default_balance
+            }
+        };
+
+        if current < cost {
+            return Err(AppError::BadRequest(
+                "insufficient balance".to_string(),
+            ));
+        }
+
+        let new_balance = current - cost;
+
+        sqlx::query(
+            "UPDATE user_billing SET balance = $1, updated_at = $2 WHERE \"user\" = $3",
+        )
+        .bind(&new_balance)
+        .bind(Utc::now())
+        .bind(user_id)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        Ok(())
+    }
+
+    async fn deduct_workspace_balance(
+        &self,
+        wk_id: Uuid,
+        cost: RustDecimal,
+    ) -> Result<(), AppError> {
+        const MAX_RETRIES: u32 = 3;
+        for attempt in 0..MAX_RETRIES {
+            match self.try_deduct_workspace_balance(wk_id, cost).await {
+                Ok(()) => return Ok(()),
+                Err(AppError::TxnError) if attempt < MAX_RETRIES - 1 => {
+                    let backoff_ms = 10 * (1 << attempt);
+                    tokio::time::sleep(tokio::time::Duration::from_millis(backoff_ms)).await;
+                    continue;
+                }
+                Err(e) => return Err(e),
+            }
+        }
+        Err(AppError::TxnError)
+    }
+
+    async fn try_deduct_workspace_balance(
+        &self,
+        wk_id: Uuid,
+        cost: RustDecimal,
+    ) -> Result<(), AppError> {
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let current: Option<RustDecimal> = sqlx::query_scalar(
+            "SELECT balance FROM wk_billing WHERE wk = $1 FOR UPDATE",
+        )
+        .bind(wk_id)
+        .fetch_optional(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let current = match current {
+            Some(balance) => balance,
+            None => {
+                let default_balance = RustDecimal::from(20);
+                let now = Utc::now();
+                sqlx::query(
+                    "INSERT INTO wk_billing (wk, balance, updated_at) \
+                     VALUES ($1, $2, $3)",
+                )
+                .bind(wk_id)
+                .bind(&default_balance)
+                .bind(now)
+                .execute(&mut **txn.inner_mut())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+                default_balance
+            }
+        };
+
+        if current < cost {
+            return Err(AppError::BadRequest(
+                "insufficient workspace balance".to_string(),
+            ));
+        }
+
+        let new_balance = current - cost;
+
+        sqlx::query(
+            "UPDATE wk_billing SET balance = $1, updated_at = $2 WHERE wk = $3",
+        )
+        .bind(&new_balance)
+        .bind(Utc::now())
+        .bind(wk_id)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        Ok(())
+    }
+}
diff --git a/lib/service/agent/compaction.rs b/lib/service/agent/compaction.rs
new file mode 100644
index 0000000..b63bb00
--- /dev/null
+++ b/lib/service/agent/compaction.rs
@@ -0,0 +1,163 @@
+use ai::agent::AgentConfig;
+use ai::agent::RigAgent;
+use ai::client::AiClient;
+use ai::agent::request::AgentRequest;
+use db::sqlx;
+use tracing::{info, warn};
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+const COMPACTION_SYSTEM_PROMPT: &str = r#"You are a conversation context compaction assistant.
+
+Your task: summarize the older portion of a conversation so the agent can continue working with only the summary + recent messages.
+
+Rules:
+- Preserve: key decisions, file paths, technical details, user preferences, unresolved questions.
+- Discard: redundant tool outputs, verbose explanations that were already acted upon, pleasantries.
+- Write in the same language as the conversation.
+- Output a concise structured summary using bullet points.
+- Keep the summary under 800 tokens.
+- Do NOT answer any questions from the conversation. Only summarize."#;
+
+const COMPACTION_TRIGGER_CHARS: usize = 80_000;
+const RECENT_MESSAGES_TO_KEEP: usize = 10;
+
+impl AppService {
+    pub(crate) async fn agent_maybe_compact(
+        &self,
+        ai_client: &AiClient,
+        model_name: &str,
+        conversation_id: Uuid,
+    ) -> Result<(), AppError> {
+        let rows: Vec<(Uuid, String, String)> = sqlx::query_as(
+            "SELECT id, role, content \
+             FROM agent_message \
+             WHERE conversation = $1 \
+               AND deleted_at IS NULL \
+               AND status = 'completed' \
+             ORDER BY created_at ASC",
+        )
+        .bind(conversation_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let total_chars: usize = rows.iter().map(|(_, _, c)| c.len()).sum();
+
+        if total_chars < COMPACTION_TRIGGER_CHARS {
+            return Ok(());
+        }
+
+        if rows.len() <= RECENT_MESSAGES_TO_KEEP {
+            return Ok(());
+        }
+
+        let split_at = rows.len().saturating_sub(RECENT_MESSAGES_TO_KEEP);
+        let older = &rows[..split_at];
+
+        let existing_summary: Option<String> = sqlx::query_scalar(
+            "SELECT compacted_summary FROM agent_conversation WHERE id = $1",
+        )
+        .bind(conversation_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .flatten();
+
+        let mut body = String::new();
+        if let Some(ref prev) = existing_summary {
+            body.push_str("<previous-summary>\n");
+            body.push_str(prev);
+            body.push_str("\n</previous-summary>\n\n");
+            body.push_str("Merge the previous summary with the new messages below:\n\n");
+        }
+        for (_, role, content) in older {
+            body.push_str(&format!("[{}]: {}\n\n", role, content));
+        }
+
+        let summary = match self
+            .agent_run_compaction_llm(ai_client, model_name, &body)
+            .await
+        {
+            Ok(s) => s,
+            Err(e) => {
+                warn!(
+                    conversation_id = %conversation_id,
+                    error = %e,
+                    "compaction LLM call failed, skipping compaction"
+                );
+                return Ok(());
+            }
+        };
+
+        sqlx::query(
+            "UPDATE agent_conversation \
+             SET compacted_summary = $1, updated_at = now() \
+             WHERE id = $2",
+        )
+        .bind(&summary)
+        .bind(conversation_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let ids: Vec<Uuid> = older.iter().map(|(id, _, _)| *id).collect();
+        if !ids.is_empty() {
+            let now = chrono::Utc::now();
+            sqlx::query(
+                "UPDATE agent_message \
+                 SET deleted_at = $1, updated_at = $1 \
+                 WHERE id = ANY($2::uuid[]) AND deleted_at IS NULL",
+            )
+            .bind(now)
+            .bind(&ids)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        info!(
+            conversation_id = %conversation_id,
+            compacted_count = older.len(),
+            kept_recent = RECENT_MESSAGES_TO_KEEP,
+            "conversation compacted successfully"
+        );
+
+        Ok(())
+    }
+
+    async fn agent_run_compaction_llm(
+        &self,
+        ai_client: &AiClient,
+        model_name: &str,
+        body: &str,
+    ) -> Result<String, AppError> {
+        let config = AgentConfig::new(model_name)
+            .map_err(|e| AppError::AiError(e))?
+            .with_system_prompt(COMPACTION_SYSTEM_PROMPT)
+            .with_temperature(Some(0.2))
+            .with_max_completion_tokens(Some(1024))
+            .with_quiet_mode(true);
+
+        let agent = RigAgent::new(ai_client.clone(), config)
+            .map_err(|e| AppError::AiError(e))?;
+
+        let request = AgentRequest::new(body);
+        let summary = agent
+            .chat(request, Vec::new())
+            .await
+            .map_err(|e| AppError::AiError(e))?;
+
+        let summary = summary.trim().to_string();
+
+        if summary.is_empty() {
+            return Err(AppError::InternalServerError(
+                "compaction returned empty summary".to_string(),
+            ));
+        }
+
+        Ok(summary)
+    }
+}
diff --git a/lib/service/agent/config.rs b/lib/service/agent/config.rs
new file mode 100644
index 0000000..0420280
--- /dev/null
+++ b/lib/service/agent/config.rs
@@ -0,0 +1,395 @@
+use ai::{
+    agent::AgentConfig,
+    client::{AiClient, AiClientConfig, EmbedConfig, EndpointConfig},
+};
+use db::sqlx::{self, types::Decimal};
+use model::{
+    agent::AgentSessionModel, ai::AiModelVersionModel, ai::AiProviderModel,
+};
+use uuid::Uuid;
+
+use super::types::SessionContext;
+use crate::error::AppError;
+use crate::AppService;
+
+impl AppService {
+    pub(crate) async fn agent_session_context(
+        &self,
+        session_id: Uuid,
+        user_id: Uuid,
+    ) -> Result<SessionContext, AppError> {
+        let session = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, tool_policy, \
+             knowledge_base_ids, variables, visibility, version, \
+             published_at, rollback_from_version, enabled, \
+             source, parent_session_id, toolset_json, \
+             memory_provider, memory_provider_config, iteration_budget, \
+             created_by, created_at, updated_at, deleted_at \
+             FROM agent_session WHERE id = $1 AND deleted_at IS NULL AND enabled = true",
+        )
+        .bind(session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        if let Some(wk_id) = session.wk {
+            let _ = self
+                .workspace_require_member(wk_id, user_id)
+                .await?;
+        } else if Some(user_id) != session.user {
+            return Err(AppError::PermissionDenied);
+        }
+
+        let model_version_id = session
+            .model_version
+            .ok_or_else(|| AppError::BadRequest("agent session has no model_version".to_string()))?;
+
+        let version = self.resolve_model_version(model_version_id).await?;
+
+        let billing_target = if session.wk.is_some() {
+            super::types::BillingTarget::Workspace
+        } else {
+            super::types::BillingTarget::User
+        };
+
+        Ok(SessionContext {
+            session_id,
+            user_id: session.user,
+            workspace_id: session.wk,
+            system_prompt: self.build_system_prompt_with_context(
+                &session,
+                user_id,
+            ).await,
+            model_version_id: version.id,
+            provider_model_name: version.provider_model_name,
+            temperature: session.temperature,
+            max_output_tokens: session.max_output_tokens,
+            tool_policy_json: session.tool_policy,
+            toolset_json: session.toolset_json,
+            variables_json: session.variables,
+            iteration_budget: session.iteration_budget,
+            memory_provider: session.memory_provider,
+            source: session.source,
+            parent_session_id: session.parent_session_id,
+            billing_target,
+        })
+    }
+    pub(crate) async fn agent_build_ai_client(
+        &self,
+        model_version_id: Uuid,
+    ) -> Result<AiClient, AppError> {
+        let version = self.resolve_model_version(model_version_id).await?;
+
+        let model_record = sqlx::query_as::<_, model::ai::AiModelModel>(
+            "SELECT id, provider, name, display_name, description, modality, \
+             context_window, input_token_limit, output_token_limit, \
+             enabled, public, created_at, updated_at, deleted_at \
+             FROM ai_model WHERE id = $1",
+        )
+        .bind(version.model)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("ai model not found".to_string()))?;
+
+        let provider = sqlx::query_as::<_, AiProviderModel>(
+            "SELECT id, name, base_url, website_url, logo_url, enabled, created_at, updated_at \
+             FROM ai_provider WHERE id = $1 AND enabled = true",
+        )
+        .bind(model_record.provider)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("ai provider not found".to_string()))?;
+
+        let base_url = provider
+            .base_url
+            .unwrap_or_else(|| self.config.ai_basic_url().unwrap_or_default());
+        let api_key = self
+            .config
+            .ai_api_key()
+            .map_err(|e| AppError::InternalServerError(format!("AI API key: {e}")))?;
+
+        let embed_base_url = self
+            .config
+            .get_embed_model_base_url()
+            .map_err(|e| AppError::InternalServerError(format!("embed base url: {e}")))?;
+        let embed_api_key = self
+            .config
+            .get_embed_model_api_key()
+            .map_err(|e| AppError::InternalServerError(format!("embed api key: {e}")))?;
+
+        let llm_config = EndpointConfig::new(&base_url, &api_key)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        let embed_endpoint = EndpointConfig::new(&embed_base_url, &embed_api_key)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        let embed_config = EmbedConfig::new(
+            embed_endpoint,
+            self.config
+                .get_embed_model_name()
+                .map_err(|e| AppError::InternalServerError(e.to_string()))?,
+            self.config
+                .get_embed_model_dimensions()
+                .map_err(|e| AppError::InternalServerError(e.to_string()))?,
+        )
+        .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let client_config = AiClientConfig::new(llm_config, embed_config)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        AiClient::new(client_config).map_err(|e| AppError::InternalServerError(e.to_string()))
+    }
+    pub(crate) fn agent_build_config(
+        &self,
+        ctx: &SessionContext,
+        max_steps_override: Option<usize>,
+    ) -> AgentConfig {
+        let mut config = AgentConfig::new(&ctx.provider_model_name)
+            .unwrap_or_else(|_| {
+                AgentConfig::new("gpt-4o").expect("default agent config")
+            });
+
+        config.model = ctx.provider_model_name.clone();
+        config.system_prompt = ctx.system_prompt.clone();
+        if let Some(ref vars_json) = ctx.variables_json {
+            if let Ok(vars) =
+                serde_json::from_str::<serde_json::Map<String, serde_json::Value>>(vars_json)
+            {
+                if !vars.is_empty() {
+                    let mut prompt = config.system_prompt.clone();
+                    let mut any_replaced = false;
+                    for (key, val) in &vars {
+                        let placeholder = format!("{{{{{}}}}}", key);
+                        if prompt.contains(&placeholder) {
+                            let replacement = match val {
+                                serde_json::Value::String(s) => s.clone(),
+                                other => other.to_string(),
+                            };
+                            prompt = prompt.replace(&placeholder, &replacement);
+                            any_replaced = true;
+                        }
+                    }
+                    if !any_replaced {
+                        prompt.push_str("\n\n<variables>\n");
+                        for (key, val) in &vars {
+                            let val_str = match val {
+                                serde_json::Value::String(s) => s.clone(),
+                                other => other.to_string(),
+                            };
+                            prompt.push_str(&format!("- {}: {}\n", key, val_str));
+                        }
+                        prompt.push_str("</variables>");
+                    }
+                    config.system_prompt = prompt;
+                }
+            }
+        }
+
+        if let Some(temp) = ctx.temperature {
+            config.temperature = Some(temp as f64);
+        }
+        if let Some(max_tok) = ctx.max_output_tokens {
+            config.max_completion_tokens = Some(max_tok as u64);
+        }
+        if let Some(max_steps) = max_steps_override {
+            config.max_iterations = max_steps;
+        }
+        if let Some(budget) = ctx.iteration_budget {
+            config.iteration_budget = budget as usize;
+        }
+        if let Some(ref policy_json) = ctx.tool_policy_json {
+            match serde_json::from_str::<serde_json::Value>(policy_json) {
+                Ok(policy) => {
+                    let allowed: Vec<String> = policy
+                        .get("allowed")
+                        .and_then(|v| v.as_array())
+                        .map(|a| {
+                            a.iter()
+                                .filter_map(|v| v.as_str().map(String::from))
+                                .collect()
+                        })
+                        .unwrap_or_default();
+                    let denied: Vec<String> = policy
+                        .get("denied")
+                        .and_then(|v| v.as_array())
+                        .map(|a| {
+                            a.iter()
+                                .filter_map(|v| v.as_str().map(String::from))
+                                .collect()
+                        })
+                        .unwrap_or_default();
+
+                    if !allowed.is_empty() || !denied.is_empty() {
+                        config = config.with_tool_policy(allowed, denied);
+                    }
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        error = %e,
+                        "failed to parse tool policy JSON, ignoring"
+                    );
+                }
+            }
+        }
+        if let Some(ref toolset_json) = ctx.toolset_json {
+            if let Ok(policy) =
+                serde_json::from_str::<serde_json::Value>(toolset_json)
+            {
+                let enabled: Vec<String> = policy
+                    .get("enabled")
+                    .and_then(|v| v.as_array())
+                    .map(|a| {
+                        a.iter()
+                            .filter_map(|v| v.as_str().map(String::from))
+                            .collect()
+                    })
+                    .unwrap_or_default();
+                let disabled: Vec<String> = policy
+                    .get("disabled")
+                    .and_then(|v| v.as_array())
+                    .map(|a| {
+                        a.iter()
+                            .filter_map(|v| v.as_str().map(String::from))
+                            .collect()
+                    })
+                    .unwrap_or_default();
+
+                if !enabled.is_empty() || !disabled.is_empty() {
+                    config = config.with_toolset_policy(enabled, disabled);
+                }
+            }
+        }
+        if ctx.memory_provider.as_deref() == Some("none") {
+            config.skip_memory = true;
+        }
+
+        config
+    }
+    async fn resolve_model_version(
+        &self,
+        id: Uuid,
+    ) -> Result<AiModelVersionModel, AppError> {
+        if let Some(version) = sqlx::query_as::<_, AiModelVersionModel>(
+            "SELECT id, model, version, provider_model_name, \
+             input_price_per_million, output_price_per_million, cached_input_price_per_million, \
+             training_cutoff, released_at, deprecated_at, enabled, created_at, updated_at \
+             FROM ai_model_version WHERE id = $1 AND enabled = true",
+        )
+        .bind(id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        {
+            return Ok(version);
+        }
+
+        let version = sqlx::query_as::<_, AiModelVersionModel>(
+            "SELECT v.id, v.model, v.version, v.provider_model_name, \
+             v.input_price_per_million, v.output_price_per_million, v.cached_input_price_per_million, \
+             v.training_cutoff, v.released_at, v.deprecated_at, v.enabled, v.created_at, v.updated_at \
+             FROM ai_model_version v \
+             INNER JOIN ai_model m ON m.id = v.model \
+             WHERE m.id = $1 AND v.enabled = true AND m.enabled = true \
+             ORDER BY v.created_at DESC LIMIT 1",
+        )
+        .bind(id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("model version not found".to_string()))?;
+
+        Ok(version)
+    }
+    pub(crate) async fn agent_resolve_pricing(
+        &self,
+        model_version_id: Uuid,
+    ) -> Result<(Option<Decimal>, Option<Decimal>), AppError> {
+        let version = sqlx::query_as::<_, AiModelVersionModel>(
+            "SELECT id, model, version, provider_model_name, \
+             input_price_per_million, output_price_per_million, cached_input_price_per_million, \
+             training_cutoff, released_at, deprecated_at, enabled, created_at, updated_at \
+             FROM ai_model_version WHERE id = $1",
+        )
+        .bind(model_version_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("model version not found".to_string()))?;
+
+        Ok((
+            version.input_price_per_million,
+            version.output_price_per_million,
+        ))
+    }
+
+    /// Build the system prompt enriched with workspace and user context.
+    async fn build_system_prompt_with_context(
+        &self,
+        session: &model::agent::AgentSessionModel,
+        user_id: Uuid,
+    ) -> String {
+        let base = session
+            .system_prompt
+            .clone()
+            .unwrap_or_else(|| ai::agent::config::default_system_prompt().to_string());
+
+        let mut context_section = String::new();
+
+        // Workspace context
+        if let Some(wk_id) = session.wk {
+            let wk: Option<(String,)> = sqlx::query_as(
+                "SELECT name FROM workspace WHERE id = $1")
+                .bind(wk_id)
+                .fetch_optional(self.db.reader())
+                .await
+                .unwrap_or(None);
+            if let Some((wk_name,)) = wk {
+                context_section.push_str(&format!(
+                    "- You are operating in workspace \"{wk_name}\" (id: {wk_id}).\n"
+                ));
+                context_section.push_str(
+                    "  All file operations, repo access, and code changes are scoped to this workspace.\n"
+                );
+            }
+        }
+
+        // User context
+        if let Some(session_user_id) = session.user {
+            let u: Option<(String, String)> = sqlx::query_as(
+                "SELECT display_name, username FROM \"user\" WHERE id = $1")
+                .bind(session_user_id)
+                .fetch_optional(self.db.reader())
+                .await
+                .unwrap_or(None);
+            if let Some((display_name, username)) = u {
+                let name = if display_name.is_empty() { &username } else { &display_name };
+                context_section.push_str(&format!(
+                    "- The current user is {name} (username: {username}, id: {session_user_id}).\n"
+                ));
+            }
+        } else {
+            let u: Option<(String, String)> = sqlx::query_as(
+                "SELECT display_name, username FROM \"user\" WHERE id = $1")
+                .bind(user_id)
+                .fetch_optional(self.db.reader())
+                .await
+                .unwrap_or(None);
+            if let Some((display_name, username)) = u {
+                let name = if display_name.is_empty() { &username } else { &display_name };
+                context_section.push_str(&format!(
+                    "- The current user is {name} (username: {username}, id: {user_id}).\n"
+                ));
+            }
+        }
+
+        if context_section.is_empty() {
+            return base;
+        }
+
+        format!(
+            "{base}\n\n<environment>\nThe following is provided for context. Always use this information\nwhen tailoring your responses, resolving references, and scoping operations.\n\n{context_section}</environment>"
+        )
+    }
+}
diff --git a/lib/service/agent/context.rs b/lib/service/agent/context.rs
new file mode 100644
index 0000000..38c8ab8
--- /dev/null
+++ b/lib/service/agent/context.rs
@@ -0,0 +1,266 @@
+use std::time::Duration;
+
+use ai::{
+    agent::request::{
+        AgentContextChunk, AgentMessage, AgentRequest,
+    },
+    client::AiClient,
+    rag::{
+        RagClient, RagConfig, RagDocument,
+    },
+};
+use db::sqlx;
+use uuid::Uuid;
+
+use super::types::SessionContext;
+use crate::error::AppError;
+use crate::AppService;
+const MAX_HISTORY_MESSAGES: u32 = 50;
+const MAX_HISTORY_CHARS: usize = 500_000;
+const MAX_HISTORY_ESTIMATED_TOKENS: u64 = 64_000;
+
+impl AppService {
+    pub(crate) async fn agent_build_request(
+        &self,
+        ai_client: &AiClient,
+        ctx: &SessionContext,
+        conversation_id: Option<Uuid>,
+        input: String,
+        timeout_secs: Option<u64>,
+    ) -> Result<AgentRequest, AppError> {
+        let mut request = AgentRequest::new(input.clone());
+        if let Some(secs) = timeout_secs {
+            request = request.with_timeout(Duration::from_secs(secs));
+        }
+        if let Some(conv_id) = conversation_id {
+            let mut all_messages = Vec::new();
+            let compacted: Option<String> = sqlx::query_scalar(
+                "SELECT compacted_summary FROM agent_conversation WHERE id = $1",
+            )
+            .bind(conv_id)
+            .fetch_optional(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+            .flatten();
+
+            if let Some(summary) = compacted {
+                all_messages.push(AgentMessage::User(format!(
+                    "[Previous conversation summary]\n{}\n[End of summary — messages below are the most recent verbatim exchanges]",
+                    summary
+                )));
+            }
+
+            let messages = self
+                .agent_load_conversation_messages(conv_id)
+                .await?;
+            all_messages.extend(messages);
+
+            request = request.with_messages(all_messages);
+        }
+        let kb_context = self
+            .agent_load_knowledge_base(ai_client, ctx, &input)
+            .await?;
+        let (memories_text, _memory_rows) = self.agent_load_memories(ctx.session_id).await?;
+
+        let mut all_context = kb_context;
+        if !memories_text.is_empty() {
+            all_context.push(AgentContextChunk::new(
+                "long_term_memory",
+                memories_text,
+            ));
+        }
+        if !all_context.is_empty() {
+            request = request.with_context(all_context);
+        }
+
+        Ok(request)
+    }
+    pub(crate) async fn agent_load_conversation_messages(
+        &self,
+        conversation_id: Uuid,
+    ) -> Result<Vec<AgentMessage>, AppError> {
+        let rows: Vec<(String, String)> = sqlx::query_as(
+            "SELECT m.role, m.content \
+             FROM agent_message m \
+             INNER JOIN agent_conversation c ON c.id = m.conversation \
+             WHERE m.conversation = $1 \
+               AND m.deleted_at IS NULL \
+               AND m.status = 'completed' \
+               AND c.deleted_at IS NULL \
+             ORDER BY m.created_at ASC \
+             LIMIT $2",
+        )
+        .bind(conversation_id)
+        .bind(MAX_HISTORY_MESSAGES as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let messages: Vec<AgentMessage> = rows
+            .into_iter()
+            .map(|(role, content)| match role.as_str() {
+                "assistant" => AgentMessage::Assistant(content),
+                _ => AgentMessage::User(content),
+            })
+            .collect();
+        let mut total_chars: usize = messages
+            .iter()
+            .map(|m| match m {
+                AgentMessage::User(c) | AgentMessage::Assistant(c) => c.len(),
+            })
+            .sum();
+
+        let mut result = messages;
+        while total_chars > MAX_HISTORY_CHARS && !result.is_empty() {
+            let removed = result.remove(0);
+            let removed_len = match &removed {
+                AgentMessage::User(c) | AgentMessage::Assistant(c) => c.len(),
+            };
+            total_chars = total_chars.saturating_sub(removed_len);
+            tracing::debug!(
+                removed_chars = removed_len,
+                remaining_chars = total_chars,
+                "trimmed oldest message to fit context window"
+            );
+        }
+        let mut estimated_tokens: u64 = result
+            .iter()
+            .map(|m| match m {
+                AgentMessage::User(c) | AgentMessage::Assistant(c) => {
+                    ai::agent::helpers::estimate_tokens(c)
+                }
+            })
+            .sum();
+        let mut trimmed_for_tokens = 0usize;
+        while estimated_tokens > MAX_HISTORY_ESTIMATED_TOKENS && !result.is_empty() {
+            let removed = result.remove(0);
+            estimated_tokens -= match &removed {
+                AgentMessage::User(c) | AgentMessage::Assistant(c) => {
+                    ai::agent::helpers::estimate_tokens(c)
+                }
+            };
+            trimmed_for_tokens += 1;
+        }
+        if trimmed_for_tokens > 0 {
+            tracing::info!(
+                trimmed = trimmed_for_tokens,
+                estimated_tokens = estimated_tokens,
+                "trimmed oldest messages to stay within token budget"
+            );
+        }
+
+        Ok(result)
+    }
+    pub(crate) async fn agent_load_knowledge_base(
+        &self,
+        ai_client: &AiClient,
+        ctx: &SessionContext,
+        query: &str,
+    ) -> Result<Vec<AgentContextChunk>, AppError> {
+        let knowledge_base_ids: Option<String> = sqlx::query_scalar(
+            "SELECT knowledge_base_ids FROM agent_session WHERE id = $1",
+        )
+        .bind(ctx.session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .flatten();
+
+        let kb_id_str = match knowledge_base_ids {
+            Some(ref s) if !s.trim().is_empty() => s.clone(),
+            _ => return Ok(Vec::new()),
+        };
+
+        let kb_ids: Vec<Uuid> = kb_id_str
+            .split(',')
+            .filter_map(|s| Uuid::parse_str(s.trim()).ok())
+            .collect();
+
+        if kb_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let qdrant_url = self
+            .config
+            .qdrant_url()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        let vector_size = self
+            .config
+            .get_embed_model_dimensions()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let rag_config = RagConfig::new(qdrant_url, "agent_knowledge", vector_size)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?
+            .with_api_key(
+                self.config
+                    .qdrant_api_key()
+                    .map_err(|e| AppError::InternalServerError(e.to_string()))?,
+            );
+
+        let rag = RagClient::connect(ai_client, rag_config)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        let mut all_hits: Vec<AgentContextChunk> = Vec::new();
+        for kb_id in &kb_ids {
+            let session_key = format!("kb:{kb_id}");
+            match rag.search_session(&session_key, query).await {
+                Ok(hits) => {
+                    for hit in hits {
+                        all_hits.push(AgentContextChunk::from(ai::rag::RagSearchHit {
+                            id: hit.id,
+                            session_id: hit.session_id,
+                            score: hit.score,
+                            content: hit.content,
+                            metadata: hit.metadata,
+                        }));
+                    }
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        kb_id = %kb_id,
+                        error = %e,
+                        "agent: RAG search failed for knowledge base, skipping"
+                    );
+                }
+            }
+        }
+
+        Ok(all_hits)
+    }
+    #[allow(dead_code)]
+    pub(crate) async fn agent_upsert_knowledge(
+        &self,
+        ai_client: &AiClient,
+        kb_id: Uuid,
+        documents: Vec<RagDocument>,
+    ) -> Result<(), AppError> {
+        let qdrant_url = self
+            .config
+            .qdrant_url()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        let vector_size = self
+            .config
+            .get_embed_model_dimensions()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let rag_config = RagConfig::new(qdrant_url, "agent_knowledge", vector_size)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?
+            .with_api_key(
+                self.config
+                    .qdrant_api_key()
+                    .map_err(|e| AppError::InternalServerError(e.to_string()))?,
+            );
+
+        let rag = RagClient::connect(ai_client, rag_config)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        rag.ensure_collection()
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let session_key = format!("kb:{kb_id}");
+        rag.upsert_documents(&session_key, documents)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        Ok(())
+    }
+}
diff --git a/lib/service/agent/conversation.rs b/lib/service/agent/conversation.rs
new file mode 100644
index 0000000..7c5fdd8
--- /dev/null
+++ b/lib/service/agent/conversation.rs
@@ -0,0 +1,627 @@
+use chrono::Utc;
+use db::sqlx;
+use model::agent::AgentConversationModel;
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+#[derive(Debug, Clone, Deserialize, ToSchema)]
+pub struct CreateConversation {
+    pub title: String,
+}
+
+#[derive(Debug, Clone, Deserialize, ToSchema)]
+pub struct UpdateConversation {
+    pub title: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, ToSchema)]
+pub struct ConversationResponse {
+    pub id: Uuid,
+    pub session_id: Uuid,
+    pub title: String,
+    pub created_by: Uuid,
+    pub last_message_at: Option<chrono::DateTime<Utc>>,
+    pub archived_at: Option<chrono::DateTime<Utc>>,
+    pub created_at: chrono::DateTime<Utc>,
+    pub updated_at: chrono::DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, ToSchema)]
+pub struct ToolCallResponse {
+    pub id: String,
+    pub name: String,
+    pub arguments: serde_json::Value,
+    pub output: Option<serde_json::Value>,
+    pub error: Option<String>,
+    pub status: String,
+    pub elapsed_ms: Option<i64>,
+}
+
+impl From<model::agent::AgentToolCallLogModel> for ToolCallResponse {
+    fn from(m: model::agent::AgentToolCallLogModel) -> Self {
+        Self {
+            id: m.tool_call_id.unwrap_or_default(),
+            name: m.tool_name,
+            arguments: m.arguments.as_deref().and_then(|s| serde_json::from_str(s).ok()).unwrap_or_default(),
+            output: m.result.as_deref().and_then(|s| serde_json::from_str(s).ok()),
+            error: m.error,
+            status: m.status,
+            elapsed_ms: m.latency_ms,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, ToSchema)]
+pub struct MessageResponse {
+    pub id: Uuid,
+    pub conversation_id: Uuid,
+    pub parent_id: Option<Uuid>,
+    pub role: String,
+    pub author: Option<Uuid>,
+    pub content: String,
+    pub content_type: String,
+    pub status: String,
+    pub model_invocation: Option<Uuid>,
+    pub reasoning_content: Option<String>,
+    #[serde(default)]
+    pub tool_calls: Vec<ToolCallResponse>,
+    pub created_at: chrono::DateTime<Utc>,
+    pub updated_at: chrono::DateTime<Utc>,
+}
+#[derive(Debug, Clone, sqlx::FromRow)]
+struct ConversationWithSessionRow {
+    pub id: Uuid,
+    pub session: Uuid,
+    pub title: String,
+    pub created_by: Uuid,
+    pub last_message_at: Option<chrono::DateTime<Utc>>,
+    pub archived_at: Option<chrono::DateTime<Utc>>,
+    pub created_at: chrono::DateTime<Utc>,
+    pub updated_at: chrono::DateTime<Utc>,
+    pub session_name: Option<String>,
+    #[allow(dead_code)]
+    pub session_wk: Option<Uuid>,
+}
+#[derive(Debug, Clone, Serialize, ToSchema)]
+pub struct ConversationWithSessionResponse {
+    pub id: Uuid,
+    pub session_id: Uuid,
+    pub session_name: Option<String>,
+    pub title: String,
+    pub created_by: Uuid,
+    pub last_message_at: Option<chrono::DateTime<Utc>>,
+    pub archived_at: Option<chrono::DateTime<Utc>>,
+    pub created_at: chrono::DateTime<Utc>,
+    pub updated_at: chrono::DateTime<Utc>,
+}
+
+impl From<ConversationWithSessionRow> for ConversationWithSessionResponse {
+    fn from(r: ConversationWithSessionRow) -> Self {
+        Self {
+            id: r.id,
+            session_id: r.session,
+            session_name: r.session_name,
+            title: r.title,
+            created_by: r.created_by,
+            last_message_at: r.last_message_at,
+            archived_at: r.archived_at,
+            created_at: r.created_at,
+            updated_at: r.updated_at,
+        }
+    }
+}
+
+impl AppService {
+    pub(crate) async fn agent_require_conversation_access(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+    ) -> Result<AgentConversationModel, AppError> {
+        let conv = sqlx::query_as::<_, AgentConversationModel>(
+            "SELECT id, session, title, created_by, last_message_at, \
+             archived_at, compacted_summary, created_at, updated_at, deleted_at \
+             FROM agent_conversation \
+             WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(conversation_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("conversation not found".to_string()))?;
+        let session: (Option<uuid::Uuid>, Option<uuid::Uuid>) = sqlx::query_as(
+            "SELECT \"user\", wk \
+             FROM agent_session \
+             WHERE id = $1 AND deleted_at IS NULL AND enabled = true",
+        )
+        .bind(conv.session)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        let (session_user, session_wk) = session;
+        if session_user != Some(user_id) {
+            if let Some(wk) = session_wk {
+                let _ = crate::AppService::workspace_require_member(
+                    &*self, wk, user_id,
+                )
+                .await?;
+            } else {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        Ok(conv)
+    }
+    async fn agent_require_session_access(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+    ) -> Result<(), AppError> {
+        let session: (Option<Uuid>, Option<Uuid>) = sqlx::query_as(
+            "SELECT \"user\", wk \
+             FROM agent_session \
+             WHERE id = $1 AND deleted_at IS NULL AND enabled = true",
+        )
+        .bind(session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        if session.0 != Some(user_id) {
+            if let Some(wk) = session.1 {
+                let _ = crate::AppService::workspace_require_member(
+                    &*self, wk, user_id,
+                )
+                .await?;
+            } else {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        Ok(())
+    }
+}
+
+impl AppService {
+    pub async fn agent_conversation_create(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+        params: CreateConversation,
+    ) -> Result<ConversationResponse, AppError> {
+        self.agent_require_session_access(user_id, session_id)
+            .await?;
+
+        let id = Uuid::now_v7();
+        let now = Utc::now();
+        let row = sqlx::query_as::<_, AgentConversationModel>(
+            "INSERT INTO agent_conversation \
+             (id, session, title, created_by, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $5) \
+             RETURNING id, session, title, created_by, last_message_at, \
+                       archived_at, compacted_summary, created_at, updated_at, deleted_at",
+        )
+        .bind(id)
+        .bind(session_id)
+        .bind(&params.title)
+        .bind(user_id)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.into())
+    }
+
+    pub async fn agent_conversation_list(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+    ) -> Result<Vec<ConversationResponse>, AppError> {
+        self.agent_require_session_access(user_id, session_id)
+            .await?;
+
+        let rows = sqlx::query_as::<_, AgentConversationModel>(
+            "SELECT id, session, title, created_by, last_message_at, \
+             archived_at, compacted_summary, created_at, updated_at, deleted_at \
+             FROM agent_conversation \
+             WHERE session = $1 AND deleted_at IS NULL \
+             ORDER BY last_message_at DESC NULLS LAST, created_at DESC \
+             LIMIT 100",
+        )
+        .bind(session_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+    pub async fn agent_conversation_list_all(
+        &self,
+        user_id: Uuid,
+        wk: Option<&str>,
+    ) -> Result<Vec<ConversationWithSessionResponse>, AppError> {
+        let rows: Vec<ConversationWithSessionRow> = if let Some(wk_name) = wk {
+            sqlx::query_as(
+                "SELECT c.id, c.session, c.title, c.created_by, c.last_message_at, \
+                 c.archived_at, c.created_at, c.updated_at, \
+                 s.name as session_name, s.wk as session_wk \
+                 FROM agent_conversation c \
+                 INNER JOIN agent_session s ON s.id = c.session \
+                 WHERE c.deleted_at IS NULL AND s.deleted_at IS NULL AND s.enabled = true \
+                   AND (s.\"user\" = $1 OR (s.wk = (SELECT id FROM workspace WHERE name = $2) AND s.wk IN (SELECT wk FROM wk_member WHERE \"user\" = $1))) \
+                 ORDER BY c.last_message_at DESC NULLS LAST, c.created_at DESC \
+                 LIMIT 100",
+            )
+            .bind(user_id)
+            .bind(wk_name)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        } else {
+            sqlx::query_as(
+                "SELECT c.id, c.session, c.title, c.created_by, c.last_message_at, \
+                 c.archived_at, c.created_at, c.updated_at, \
+                 s.name as session_name, s.wk as session_wk \
+                 FROM agent_conversation c \
+                 INNER JOIN agent_session s ON s.id = c.session \
+                 WHERE c.deleted_at IS NULL AND s.deleted_at IS NULL AND s.enabled = true \
+                   AND s.\"user\" = $1 \
+                 ORDER BY c.last_message_at DESC NULLS LAST, c.created_at DESC \
+                 LIMIT 100",
+            )
+            .bind(user_id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        };
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    pub async fn agent_conversation_get(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+    ) -> Result<ConversationResponse, AppError> {
+        Ok(self
+            .agent_require_conversation_access(user_id, conversation_id)
+            .await?
+            .into())
+    }
+
+    pub async fn agent_conversation_update(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+        params: UpdateConversation,
+    ) -> Result<ConversationResponse, AppError> {
+        let existing = self
+            .agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+
+        let title = params.title.unwrap_or(existing.title);
+        let now = Utc::now();
+
+        let row = sqlx::query_as::<_, AgentConversationModel>(
+            "UPDATE agent_conversation SET title = $1, updated_at = $2 \
+             WHERE id = $3 AND deleted_at IS NULL \
+             RETURNING id, session, title, created_by, last_message_at, \
+                       archived_at, compacted_summary, created_at, updated_at, deleted_at",
+        )
+        .bind(&title)
+        .bind(now)
+        .bind(conversation_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.into())
+    }
+
+    pub async fn agent_conversation_delete(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+    ) -> Result<(), AppError> {
+        self.agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+
+        let now = Utc::now();
+        let rows = sqlx::query(
+            "UPDATE agent_conversation SET deleted_at = $1, updated_at = $1 \
+             WHERE id = $2 AND deleted_at IS NULL",
+        )
+        .bind(now)
+        .bind(conversation_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if rows.rows_affected() == 0 {
+            return Err(AppError::NotFound("conversation not found".to_string()));
+        }
+        Ok(())
+    }
+
+    pub async fn agent_conversation_archive(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+    ) -> Result<ConversationResponse, AppError> {
+        self.agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+
+        let now = Utc::now();
+        let row = sqlx::query_as::<_, AgentConversationModel>(
+            "UPDATE agent_conversation SET archived_at = $1, updated_at = $1 \
+             WHERE id = $2 AND deleted_at IS NULL \
+             RETURNING id, session, title, created_by, last_message_at, \
+                       archived_at, compacted_summary, created_at, updated_at, deleted_at",
+        )
+        .bind(now)
+        .bind(conversation_id)
+        .fetch_optional(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("conversation not found".to_string()))?;
+
+        Ok(row.into())
+    }
+
+    pub async fn agent_conversation_unarchive(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+    ) -> Result<ConversationResponse, AppError> {
+        self.agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+
+        let now = Utc::now();
+        let row = sqlx::query_as::<_, AgentConversationModel>(
+            "UPDATE agent_conversation SET archived_at = NULL, updated_at = $1 \
+             WHERE id = $2 AND deleted_at IS NULL \
+             RETURNING id, session, title, created_by, last_message_at, \
+                       archived_at, compacted_summary, created_at, updated_at, deleted_at",
+        )
+        .bind(now)
+        .bind(conversation_id)
+        .fetch_optional(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("conversation not found".to_string()))?;
+
+        Ok(row.into())
+    }
+}
+
+impl AppService {
+    pub async fn agent_message_list(
+        &self,
+        user_id: Uuid,
+        conversation_id: Uuid,
+        limit: Option<u32>,
+        before: Option<Uuid>,
+    ) -> Result<Vec<MessageResponse>, AppError> {
+        self.agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+
+        let limit = limit.unwrap_or(50).min(100) as i64;
+
+        let rows = if let Some(before_id) = before {
+            sqlx::query_as::<_, model::agent::AgentMessageModel>(
+                "SELECT id, conversation, parent, role, author, content, content_type, \
+                 status, model_invocation, reasoning_content, created_at, updated_at, deleted_at \
+                 FROM agent_message \
+                 WHERE conversation = $1 AND deleted_at IS NULL \
+                   AND created_at < (SELECT created_at FROM agent_message WHERE id = $2 AND conversation = $1) \
+                 ORDER BY created_at DESC LIMIT $3",
+            )
+            .bind(conversation_id)
+            .bind(before_id)
+            .bind(limit)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        } else {
+            sqlx::query_as::<_, model::agent::AgentMessageModel>(
+                "SELECT id, conversation, parent, role, author, content, content_type, \
+                 status, model_invocation, reasoning_content, created_at, updated_at, deleted_at \
+                 FROM agent_message \
+                 WHERE conversation = $1 AND deleted_at IS NULL \
+                 ORDER BY created_at DESC LIMIT $2",
+            )
+            .bind(conversation_id)
+            .bind(limit)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        };
+
+        // Fetch tool calls for all assistant messages in one query.
+        let message_ids: Vec<Uuid> = rows.iter().map(|r| r.id).collect();
+        let tool_call_logs = if !message_ids.is_empty() {
+            sqlx::query_as::<_, model::agent::AgentToolCallLogModel>(
+                "SELECT id, invocation, session, conversation, message, tool_call_id, \
+                 tool_name, arguments, result, error, status, \
+                 started_at, finished_at, latency_ms \
+                 FROM agent_tool_call_log \
+                 WHERE message = ANY($1) \
+                 ORDER BY started_at ASC",
+            )
+            .bind(&message_ids)
+            .fetch_all(self.db.reader())
+            .await
+            .unwrap_or_default()
+        } else {
+            Vec::new()
+        };
+
+        // Group tool calls by message_id.
+        let mut tool_calls_by_message: std::collections::HashMap<Uuid, Vec<ToolCallResponse>> =
+            std::collections::HashMap::new();
+        for log in tool_call_logs {
+            if let Some(msg_id) = log.message {
+                tool_calls_by_message
+                    .entry(msg_id)
+                    .or_default()
+                    .push(log.into());
+            }
+        }
+
+        let mut messages: Vec<MessageResponse> = rows
+            .into_iter()
+            .map(|row| {
+                let mut msg: MessageResponse = row.into();
+                msg.tool_calls = tool_calls_by_message
+                    .remove(&msg.id)
+                    .unwrap_or_default();
+                msg
+            })
+            .collect();
+        messages.reverse();
+        Ok(messages)
+    }
+    pub async fn agent_conversation_fork(
+        &self,
+        user_id: Uuid,
+        source_conversation_id: Uuid,
+        up_to_message_id: Option<Uuid>,
+        title_override: Option<&str>,
+    ) -> Result<ConversationResponse, AppError> {
+        let source = self
+            .agent_require_conversation_access(user_id, source_conversation_id)
+            .await?;
+
+        let session_id = source.session;
+        let base_title = title_override
+            .map(|t| t.to_string())
+            .unwrap_or_else(|| format!("{} (fork)", source.title));
+
+        let new_id = Uuid::now_v7();
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_conversation \
+             (id, session, title, created_by, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $5)",
+        )
+        .bind(new_id)
+        .bind(session_id)
+        .bind(&base_title)
+        .bind(user_id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let messages = if let Some(msg_id) = up_to_message_id {
+            sqlx::query_as::<_, model::agent::AgentMessageModel>(
+                "SELECT id, conversation, parent, role, author, content, content_type, \
+                 status, model_invocation, reasoning_content, \
+                 created_at, updated_at, deleted_at \
+                 FROM agent_message \
+                 WHERE conversation = $1 \
+                   AND deleted_at IS NULL \
+                   AND created_at <= (SELECT created_at FROM agent_message WHERE id = $2) \
+                 ORDER BY created_at ASC",
+            )
+            .bind(source_conversation_id)
+            .bind(msg_id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        } else {
+            sqlx::query_as::<_, model::agent::AgentMessageModel>(
+                "SELECT id, conversation, parent, role, author, content, content_type, \
+                 status, model_invocation, reasoning_content, \
+                 created_at, updated_at, deleted_at \
+                 FROM agent_message \
+                 WHERE conversation = $1 AND deleted_at IS NULL \
+                 ORDER BY created_at ASC",
+            )
+            .bind(source_conversation_id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        };
+
+        for msg in &messages {
+            let new_msg_id = Uuid::now_v7();
+            sqlx::query(
+                "INSERT INTO agent_message \
+                 (id, conversation, parent, role, author, content, content_type, \
+                  status, model_invocation, reasoning_content, created_at, updated_at) \
+                 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $11)",
+            )
+            .bind(new_msg_id)
+            .bind(new_id)
+            .bind::<Option<Uuid>>(None)
+            .bind(&msg.role)
+            .bind(msg.author)
+            .bind(&msg.content)
+            .bind(&msg.content_type)
+            .bind(&msg.status)
+            .bind(msg.model_invocation)
+            .bind(&msg.reasoning_content)
+            .bind(msg.created_at)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+            let _ = sqlx::query(
+                "INSERT INTO agent_message_fork \
+                 (source_message, forked_conversation, forked_by, created_at) \
+                 VALUES ($1, $2, $3, $4)",
+            )
+            .bind(msg.id)
+            .bind(new_id)
+            .bind(user_id)
+            .bind(now)
+            .execute(self.db.writer())
+            .await;
+        }
+
+        self.agent_conversation_get(user_id, new_id).await
+    }
+}
+
+impl From<AgentConversationModel> for ConversationResponse {
+    fn from(m: AgentConversationModel) -> Self {
+        Self {
+            id: m.id,
+            session_id: m.session,
+            title: m.title,
+            created_by: m.created_by,
+            last_message_at: m.last_message_at,
+            archived_at: m.archived_at,
+            created_at: m.created_at,
+            updated_at: m.updated_at,
+        }
+    }
+}
+
+impl From<model::agent::AgentMessageModel> for MessageResponse {
+    fn from(m: model::agent::AgentMessageModel) -> Self {
+        Self {
+            id: m.id,
+            conversation_id: m.conversation,
+            parent_id: m.parent,
+            role: m.role,
+            author: m.author,
+            content: m.content,
+            content_type: m.content_type,
+            status: m.status,
+            model_invocation: m.model_invocation,
+            reasoning_content: m.reasoning_content,
+            tool_calls: Vec::new(),
+            created_at: m.created_at,
+            updated_at: m.updated_at,
+        }
+    }
+}
diff --git a/lib/service/agent/git_tools/blame.rs b/lib/service/agent/git_tools/blame.rs
new file mode 100644
index 0000000..1384ede
--- /dev/null
+++ b/lib/service/agent/git_tools/blame.rs
@@ -0,0 +1,90 @@
+use ai::error::AiResult;
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::blame_service_client::BlameServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, arg_opt_str, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+pub struct GitBlameTool;
+
+impl GitBlameTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitBlameTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitBlameTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_blame" }
+
+    fn description(&self) -> &'static str {
+        "Blame a file to see which commits authored each line range."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "path": { "type": "string", "description": "File path to blame" },
+                "rev": { "type": "string", "description": "Revision/branch (optional)" },
+                "start_line": { "type": "integer", "description": "Start line number (optional)" },
+                "end_line": { "type": "integer", "description": "End line number (optional)" }
+            },
+            "required": ["workspace", "repo", "path"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let path = arg_str(&args, "path")?;
+        let rev = arg_opt_str(&args, "rev").map(String::from);
+        let start_line = args.get("start_line").and_then(|v| v.as_u64()).map(|v| v as u32);
+        let end_line = args.get("end_line").and_then(|v| v.as_u64()).map(|v| v as u32);
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = BlameServiceClient::new(git.channel.clone());
+
+        if let (Some(start), Some(end)) = (start_line, end_line) {
+            let resp = client
+                .blame_lines(p::BlameLinesRequest {
+                    repo_id: repo.id.to_string(), path: path.to_string(), rev,
+                    start_line: start, end_line: end,
+                })
+                .await.map_err(rpc_err)?.into_inner();
+
+            let lines: Vec<Value> = resp.lines.iter().map(|l| json!({
+                "line_no": l.line_no,
+                "content": l.content,
+                "commit_oid": l.commit_oid.as_ref().map(|o| &o.value),
+            })).collect();
+
+            Ok(json!({ "lines": lines, "count": lines.len() }))
+        } else {
+            let resp = client
+                .blame_file(p::BlameFileRequest {
+                    repo_id: repo.id.to_string(), path: path.to_string(), rev, options: None,
+                })
+                .await.map_err(rpc_err)?.into_inner();
+
+            let hunks: Vec<Value> = resp.hunks.iter().map(|h| json!({
+                "commit_oid": h.commit_oid.as_ref().map(|o| &o.value),
+                "final_start_line": h.final_start_line,
+                "final_lines": h.final_lines,
+            })).collect();
+
+            Ok(json!({ "hunks": hunks, "count": hunks.len() }))
+        }
+    }
+}
diff --git a/lib/service/agent/git_tools/branch.rs b/lib/service/agent/git_tools/branch.rs
new file mode 100644
index 0000000..f80f58b
--- /dev/null
+++ b/lib/service/agent/git_tools/branch.rs
@@ -0,0 +1,302 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::branch_service_client::BranchServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+pub struct GitBranchListTool;
+
+impl GitBranchListTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitBranchListTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitBranchListTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_branch_list" }
+
+    fn description(&self) -> &'static str {
+        "List all branches in a repository with their HEAD commit OID."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" }
+            },
+            "required": ["workspace", "repo"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = BranchServiceClient::new(git.channel.clone());
+        let resp = client
+            .branch_list(p::BranchListRequest { repo_id: repo.id.to_string() })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let branches: Vec<Value> = resp.branches.iter().map(|b| json!({
+            "name": b.name,
+            "oid": b.oid.as_ref().map(|o| &o.value).unwrap_or(&String::new()),
+            "is_head": b.is_head,
+            "is_current": b.is_current,
+        })).collect();
+
+        Ok(json!({ "branches": branches, "count": branches.len() }))
+    }
+}
+
+pub struct GitBranchInfoTool;
+
+impl GitBranchInfoTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitBranchInfoTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitBranchInfoTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_branch_info" }
+
+    fn description(&self) -> &'static str {
+        "Get detailed information about a single branch, including its HEAD OID and upstream."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "branch": { "type": "string", "description": "Branch name" }
+            },
+            "required": ["workspace", "repo", "branch"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let branch = arg_str(&args, "branch")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = BranchServiceClient::new(git.channel.clone());
+        let resp = client
+            .branch_info(p::BranchInfoRequest {
+                repo_id: repo.id.to_string(),
+                branch: branch.to_string(),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let b = resp.branch.ok_or_else(|| AiError::Config(format!("branch '{branch}' not found")))?;
+        Ok(json!({
+            "name": b.name,
+            "oid": b.oid.as_ref().map(|o| &o.value),
+            "is_head": b.is_head,
+            "is_current": b.is_current,
+            "upstream": b.upstream,
+        }))
+    }
+}
+
+pub struct GitBranchAheadBehindTool;
+
+impl GitBranchAheadBehindTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitBranchAheadBehindTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitBranchAheadBehindTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_branch_ahead_behind" }
+
+    fn description(&self) -> &'static str {
+        "Compare a local branch with its remote tracking branch. Returns commits ahead and behind."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "local_branch": { "type": "string", "description": "Local branch name" },
+                "remote_branch": { "type": "string", "description": "Remote tracking branch name" }
+            },
+            "required": ["workspace", "repo", "local_branch", "remote_branch"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let local_branch = arg_str(&args, "local_branch")?;
+        let remote_branch = arg_str(&args, "remote_branch")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = BranchServiceClient::new(git.channel.clone());
+        let resp = client
+            .branch_ahead_behind(p::BranchAheadBehindRequest {
+                repo_id: repo.id.to_string(),
+                local_branch: local_branch.to_string(),
+                remote_branch: remote_branch.to_string(),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        Ok(json!({ "ahead": resp.ahead, "behind": resp.behind }))
+    }
+}
+
+pub struct GitBranchDeleteTool;
+
+impl GitBranchDeleteTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitBranchDeleteTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitBranchDeleteTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_branch_delete" }
+
+    fn description(&self) -> &'static str {
+        "Delete a branch from the repository. Requires write access."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "name": { "type": "string", "description": "Branch name to delete" },
+                "force": { "type": "boolean", "description": "Force delete (even if not merged)" }
+            },
+            "required": ["workspace", "repo", "name"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let name = arg_str(&args, "name")?;
+        let force = args.get("force").and_then(|v| v.as_bool()).unwrap_or(false);
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = BranchServiceClient::new(git.channel.clone());
+        client
+            .branch_delete(p::BranchDeleteRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(p::BranchDeleteParams {
+                    name: name.to_string(),
+                    force,
+                }),
+            })
+            .await
+            .map_err(rpc_err)?;
+
+        Ok(json!({ "success": true, "branch": name }))
+    }
+}
+
+pub struct GitCreateBranchTool;
+
+impl GitCreateBranchTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitCreateBranchTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitCreateBranchTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_create_branch" }
+
+    fn description(&self) -> &'static str {
+        "Create a new branch in a repository. Requires write access."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "name": { "type": "string", "description": "New branch name" },
+                "oid": { "type": "string", "description": "Commit OID to branch from" },
+                "force": { "type": "boolean", "description": "Force create (overwrite existing)" }
+            },
+            "required": ["workspace", "repo", "name", "oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let name = arg_str(&args, "name")?;
+        let oid = arg_str(&args, "oid")?;
+        let force = args.get("force").and_then(|v| v.as_bool()).unwrap_or(false);
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = BranchServiceClient::new(git.channel.clone());
+        client
+            .branch_fork(p::BranchForkRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(p::BranchForkParams {
+                    name: name.to_string(),
+                    oid: Some(p::ObjectId { value: oid.to_string() }),
+                    force,
+                }),
+            })
+            .await
+            .map_err(rpc_err)?;
+
+        Ok(json!({ "success": true, "branch": name, "oid": oid }))
+    }
+}
diff --git a/lib/service/agent/git_tools/commit.rs b/lib/service/agent/git_tools/commit.rs
new file mode 100644
index 0000000..0eb232b
--- /dev/null
+++ b/lib/service/agent/git_tools/commit.rs
@@ -0,0 +1,438 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::commit_service_client::CommitServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, arg_opt_str, arg_u64, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+pub struct GitCommitHistoryTool;
+
+impl GitCommitHistoryTool {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for GitCommitHistoryTool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl FunctionCall for GitCommitHistoryTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str {
+        "git_commit_history"
+    }
+
+    fn description(&self) -> &'static str {
+        "List recent commits on a branch. Returns commit OID, message, author, and timestamp."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": {
+                    "type": "string",
+                    "description": "Workspace name (e.g. 'my-org')"
+                },
+                "repo": {
+                    "type": "string",
+                    "description": "Repository name"
+                },
+                "branch": {
+                    "type": "string",
+                    "description": "Branch name (optional, defaults to default branch)"
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max commits to return (default 20, max 100)"
+                },
+                "skip": {
+                    "type": "integer",
+                    "description": "Number of commits to skip (for pagination)"
+                }
+            },
+            "required": ["workspace", "repo"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let branch = arg_opt_str(&args, "branch").map(String::from);
+        let limit = arg_u64(&args, "limit", 20).min(100);
+        let skip = arg_u64(&args, "skip", 0);
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = CommitServiceClient::new(git.channel.clone());
+        let resp = client
+            .commit_history(p::CommitHistoryRequest {
+                repo_id: repo.id.to_string(),
+                limit,
+                skip,
+                sort: p::CommitWalkSort::Time as i32,
+                branch,
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let commits: Vec<Value> = resp
+            .commits
+            .iter()
+            .map(|c| {
+                json!({
+                    "oid": c.oid.as_ref().map(|o| &o.value).unwrap_or(&String::new()),
+                    "summary": c.summary,
+                    "message": c.message,
+                    "author_name": c.author.as_ref().map(|a| &a.name).unwrap_or(&String::new()),
+                    "author_email": c.author.as_ref().map(|a| &a.email).unwrap_or(&String::new()),
+                    "time": c.author.as_ref().map(|a| a.time_secs).unwrap_or(0),
+                })
+            })
+            .collect();
+
+        Ok(json!({ "commits": commits, "count": commits.len() }))
+    }
+}
+
+pub struct GitCommitInfoTool;
+
+impl GitCommitInfoTool {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for GitCommitInfoTool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl FunctionCall for GitCommitInfoTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str {
+        "git_commit_info"
+    }
+
+    fn description(&self) -> &'static str {
+        "Get detailed information about a specific commit by its OID."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "oid": { "type": "string", "description": "Commit OID (SHA)" }
+            },
+            "required": ["workspace", "repo", "oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let oid = arg_str(&args, "oid")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = CommitServiceClient::new(git.channel.clone());
+        let resp = client
+            .commit_info(p::CommitInfoRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: oid.to_string() }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let c = resp
+            .commit
+            .ok_or_else(|| AiError::Response("commit not found".to_string()))?;
+        let parent_ids: Vec<String> = c.parent_ids.iter().map(|o| o.value.clone()).collect();
+
+        Ok(json!({
+            "oid": c.oid.as_ref().map(|o| &o.value),
+            "summary": c.summary,
+            "message": c.message,
+            "author_name": c.author.as_ref().map(|a| &a.name),
+            "author_email": c.author.as_ref().map(|a| &a.email),
+            "author_time": c.author.as_ref().map(|a| a.time_secs),
+            "committer_name": c.committer.as_ref().map(|a| &a.name),
+            "tree_id": c.tree_id.as_ref().map(|o| &o.value),
+            "parent_ids": parent_ids,
+        }))
+    }
+}
+
+
+pub struct GitCommitExistsTool;
+
+impl GitCommitExistsTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitCommitExistsTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitCommitExistsTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_commit_exists" }
+
+    fn description(&self) -> &'static str {
+        "Check whether a specific commit OID exists in the repository."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "oid": { "type": "string", "description": "Commit OID (SHA)" }
+            },
+            "required": ["workspace", "repo", "oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let oid = arg_str(&args, "oid")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = CommitServiceClient::new(git.channel.clone());
+        let resp = client
+            .commit_exists(p::CommitExistsRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: oid.to_string() }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        Ok(json!({ "exists": resp.exists }))
+    }
+}
+
+
+
+pub struct GitCherryPickTool;
+
+impl GitCherryPickTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitCherryPickTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitCherryPickTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_cherry_pick" }
+
+    fn description(&self) -> &'static str {
+        "Cherry-pick a commit onto the current branch. Requires write access."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "oid": { "type": "string", "description": "Commit OID to cherry-pick" },
+                "message": { "type": "string", "description": "Override commit message (optional)" },
+                "update_ref": { "type": "string", "description": "Branch ref to update (optional)" }
+            },
+            "required": ["workspace", "repo", "oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let oid = arg_str(&args, "oid")?;
+        let message = args.get("message").and_then(|v| v.as_str()).map(String::from);
+        let update_ref = arg_opt_str(&args, "update_ref").map(String::from);
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = CommitServiceClient::new(git.channel.clone());
+        let resp = client
+            .cherry_pick(p::CherryPickRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(p::CommitCherryPickParams {
+                    cherrypick_oid: Some(p::ObjectId { value: oid.to_string() }),
+                    message,
+                    update_ref,
+                    ..Default::default()
+                }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        Ok(json!({
+            "success": true,
+            "new_oid": resp.oid.as_ref().map(|o| &o.value),
+        }))
+    }
+}
+
+
+pub struct GitCommitCreateTool;
+
+impl GitCommitCreateTool {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for GitCommitCreateTool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl FunctionCall for GitCommitCreateTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str {
+        "git_commit_create"
+    }
+
+    fn description(&self) -> &'static str {
+        "Create a commit with new or updated files in a workspace repository. Author is set to the requesting user, committer is redpanda <redpanda@gitdata.ai>. Provide workspace name, repo name, branch, commit message, and a list of files (path and content for each)."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": {
+                    "type": "string",
+                    "description": "Workspace name (e.g. 'my-org')"
+                },
+                "repo": {
+                    "type": "string",
+                    "description": "Repository name"
+                },
+                "branch": {
+                    "type": "string",
+                    "description": "Branch name to commit to (e.g. 'main'). If the branch does not exist, it will be created."
+                },
+                "message": {
+                    "type": "string",
+                    "description": "Commit message"
+                },
+                "files": {
+                    "type": "array",
+                    "description": "List of file changes",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "path": {
+                                "type": "string",
+                                "description": "File path relative to repo root (e.g. 'src/main.rs')"
+                            },
+                            "content": {
+                                "type": "string",
+                                "description": "File content as a string"
+                            }
+                        },
+                        "required": ["path", "content"]
+                    }
+                }
+            },
+            "required": ["workspace", "repo", "branch", "message", "files"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let branch = arg_str(&args, "branch")?;
+        let message = arg_str(&args, "message")?;
+
+        let files_val = args
+            .get("files")
+            .and_then(|v| v.as_array())
+            .ok_or_else(|| AiError::Config("'files' must be an array of {path, content} objects".to_string()))?;
+
+        let mut file_changes: Vec<super::helpers::FileChange> = Vec::new();
+        for f in files_val {
+            let path = f
+                .get("path")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| AiError::Config("each file must have a 'path' field".to_string()))?;
+            let content = f
+                .get("content")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| AiError::Config("each file must have a 'content' field".to_string()))?;
+            file_changes.push(super::helpers::FileChange {
+                path: path.to_string(),
+                content: content.as_bytes().to_vec(),
+            });
+        }
+
+        if file_changes.is_empty() {
+            return Err(AiError::Config("'files' array must not be empty".to_string()));
+        }
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = CommitServiceClient::new(git.channel.clone());
+        let resp = client
+            .create_commit(tonic::Request::new(p::CreateCommitRequest {
+                repo_id: repo.id.to_string(),
+                branch: branch.to_string(),
+                message: message.to_string(),
+                author_name: ctx.user_id.to_string(),
+                author_email: format!("{}@gitdata.ai", ctx.user_id),
+                committer_name: "redpanda".to_string(),
+                committer_email: "redpanda@gitdata.ai".to_string(),
+                files: file_changes
+                    .into_iter()
+                    .map(|fc| p::FileChange {
+                        path: fc.path,
+                        content: fc.content,
+                    })
+                    .collect(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        Ok(json!({
+            "success": true,
+            "oid": resp.oid.as_ref().map(|o| &o.value),
+            "files_committed": files_val.len(),
+        }))
+    }
+}
diff --git a/lib/service/agent/git_tools/diff.rs b/lib/service/agent/git_tools/diff.rs
new file mode 100644
index 0000000..f5c12d4
--- /dev/null
+++ b/lib/service/agent/git_tools/diff.rs
@@ -0,0 +1,188 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::diff_service_client::DiffServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+pub struct GitDiffStatsTool;
+
+impl GitDiffStatsTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitDiffStatsTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitDiffStatsTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_diff_stats" }
+
+    fn description(&self) -> &'static str {
+        "Get diff statistics between two commits: files changed, insertions, deletions."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "old_oid": { "type": "string", "description": "Base commit OID" },
+                "new_oid": { "type": "string", "description": "Target commit OID" }
+            },
+            "required": ["workspace", "repo", "old_oid", "new_oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let old_oid = arg_str(&args, "old_oid")?;
+        let new_oid = arg_str(&args, "new_oid")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = DiffServiceClient::new(git.channel.clone());
+        let resp = client
+            .diff_stats(p::DiffStatsRequest {
+                repo_id: repo.id.to_string(),
+                old_oid: Some(p::ObjectId { value: old_oid.to_string() }),
+                new_oid: Some(p::ObjectId { value: new_oid.to_string() }),
+                options: None,
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let result = resp.result.ok_or_else(|| AiError::Response("no diff result".to_string()))?;
+        let stats = result.stats.ok_or_else(|| AiError::Response("no stats".to_string()))?;
+
+        let files: Vec<Value> = result.deltas.iter().map(|d| {
+            let status = match p::DiffDeltaStatus::try_from(d.status) {
+                Ok(p::DiffDeltaStatus::Added) => "added",
+                Ok(p::DiffDeltaStatus::Deleted) => "deleted",
+                Ok(p::DiffDeltaStatus::Modified) => "modified",
+                Ok(p::DiffDeltaStatus::Renamed) => "renamed",
+                _ => "unknown",
+            };
+            let old_path = d.old_file.as_ref().and_then(|f| f.path.as_deref()).unwrap_or("");
+            let new_path = d.new_file.as_ref().and_then(|f| f.path.as_deref()).unwrap_or("");
+            json!({ "status": status, "old_path": old_path, "new_path": new_path, "hunks": d.hunks.len() })
+        }).collect();
+
+        Ok(json!({
+            "files_changed": stats.files_changed,
+            "insertions": stats.insertions,
+            "deletions": stats.deletions,
+            "files": files,
+        }))
+    }
+}
+
+pub struct GitDiffPatchTool;
+
+impl GitDiffPatchTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitDiffPatchTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitDiffPatchTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_diff_patch" }
+
+    fn description(&self) -> &'static str {
+        "Get the full diff (unified format) between two commits, including line-level changes."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "old_oid": { "type": "string", "description": "Base commit OID" },
+                "new_oid": { "type": "string", "description": "Target commit OID" },
+                "context_lines": { "type": "integer", "description": "Lines of context around changes (default 3)" }
+            },
+            "required": ["workspace", "repo", "old_oid", "new_oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let old_oid = arg_str(&args, "old_oid")?;
+        let new_oid = arg_str(&args, "new_oid")?;
+        let ctx_lines = args.get("context_lines").and_then(|v| v.as_u64()).unwrap_or(3) as u32;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = DiffServiceClient::new(git.channel.clone());
+        let resp = client
+            .diff_patch(p::DiffPatchRequest {
+                repo_id: repo.id.to_string(),
+                old_oid: Some(p::ObjectId { value: old_oid.to_string() }),
+                new_oid: Some(p::ObjectId { value: new_oid.to_string() }),
+                options: Some(p::DiffOptions {
+                    context_lines: ctx_lines,
+                    ..Default::default()
+                }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let result = resp.result.ok_or_else(|| AiError::Response("no diff result".to_string()))?;
+        let stats = result.stats.ok_or_else(|| AiError::Response("no stats".to_string()))?;
+
+        let mut patch_text = String::new();
+        for delta in &result.deltas {
+            let status = match p::DiffDeltaStatus::try_from(delta.status) {
+                Ok(p::DiffDeltaStatus::Added) => "added",
+                Ok(p::DiffDeltaStatus::Deleted) => "deleted",
+                Ok(p::DiffDeltaStatus::Modified) => "modified",
+                Ok(p::DiffDeltaStatus::Renamed) => "renamed",
+                _ => "unknown",
+            };
+            let old = delta.old_file.as_ref().and_then(|f| f.path.as_deref()).unwrap_or("unknown");
+            let new = delta.new_file.as_ref().and_then(|f| f.path.as_deref()).unwrap_or("unknown");
+            patch_text.push_str(&format!("--- {}\n+++ {}\n@@ status: {status} @@\n", old, new));
+
+            for hunk in &delta.hunks {
+                patch_text.push_str(&hunk.header);
+                patch_text.push('\n');
+                for line in &delta.lines {
+                    patch_text.push_str(&format!("{}{}\n", line.origin, line.content));
+                }
+                patch_text.push('\n');
+            }
+        }
+
+        let truncated = patch_text.len() > 32_000;
+        if truncated {
+            patch_text = format!("{}...(truncated)", &patch_text[..32_000]);
+        }
+
+        Ok(json!({
+            "files_changed": stats.files_changed,
+            "insertions": stats.insertions,
+            "deletions": stats.deletions,
+            "patch": patch_text,
+            "truncated": truncated,
+        }))
+    }
+}
diff --git a/lib/service/agent/git_tools/helpers.rs b/lib/service/agent/git_tools/helpers.rs
new file mode 100644
index 0000000..e0843fb
--- /dev/null
+++ b/lib/service/agent/git_tools/helpers.rs
@@ -0,0 +1,112 @@
+use ai::error::{AiError, AiResult};
+
+#[derive(Debug, Clone)]
+pub struct FileChange {
+    pub path: String,
+    pub content: Vec<u8>,
+}
+use ai::tool::register::ToolRegister;
+use db::sqlx;
+use model::repos::RepoModel;
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::agent::run::{AppAgentContext, GitAgentContext};
+
+pub fn register_git_tools(tools: &mut ToolRegister<AppAgentContext>) {
+    tools.register(super::commit::GitCommitHistoryTool::new());
+    tools.register(super::commit::GitCommitInfoTool::new());
+    tools.register(super::commit::GitCommitExistsTool::new());
+    tools.register(super::commit::GitCherryPickTool::new());
+    tools.register(super::commit::GitCommitCreateTool::new());
+    tools.register(super::branch::GitBranchListTool::new());
+    tools.register(super::branch::GitBranchInfoTool::new());
+    tools.register(super::branch::GitBranchAheadBehindTool::new());
+    tools.register(super::branch::GitCreateBranchTool::new());
+    tools.register(super::branch::GitBranchDeleteTool::new());
+    tools.register(super::tree::GitTreeEntriesTool::new());
+    tools.register(super::tree::GitFileContentTool::new());
+    tools.register(super::diff::GitDiffStatsTool::new());
+    tools.register(super::diff::GitDiffPatchTool::new());
+    tools.register(super::blame::GitBlameTool::new());
+    tools.register(super::tag::GitTagListTool::new());
+    tools.register(super::tag::GitTagInfoTool::new());
+    tools.register(super::tag::GitCreateTagTool::new());
+    tools.register(super::tag::GitDeleteTagTool::new());
+    tools.register(super::merge::GitMergeBaseTool::new());
+    tools.register(super::merge::GitMergeAnalysisTool::new());
+    tools.register(super::merge::GitMergeIsConflictedTool::new());
+}
+
+pub(super) async fn require_repo_member(
+    git: &GitAgentContext,
+    user_id: Uuid,
+    workspace_name: &str,
+    repo_name: &str,
+) -> AiResult<RepoModel> {
+    let wk_id: Uuid = sqlx::query_scalar(
+        "SELECT id FROM workspace WHERE name = $1",
+    )
+    .bind(workspace_name)
+    .fetch_optional(git.db.reader())
+    .await
+    .map_err(AiError::Database)?
+    .ok_or_else(|| AiError::Config(format!("workspace '{workspace_name}' not found")))?;
+
+    let is_member: i64 = sqlx::query_scalar(
+        "SELECT COUNT(*) FROM wk_member \
+         WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+    )
+    .bind(wk_id)
+    .bind(user_id)
+    .fetch_one(git.db.reader())
+    .await
+    .map_err(AiError::Database)?;
+
+    if is_member == 0 {
+        return Err(AiError::Config(format!(
+            "user is not a member of workspace '{workspace_name}'"
+        )));
+    }
+
+    let repo: RepoModel = sqlx::query_as(
+        "SELECT id, wk, name, description, default_branch, visibility, \
+         size_bytes, is_archived, is_template, is_mirror, created_by, \
+         storage_path, created_at, updated_at, deleted_at \
+         FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL",
+    )
+    .bind(wk_id)
+    .bind(repo_name)
+    .fetch_optional(git.db.reader())
+    .await
+    .map_err(AiError::Database)?
+    .ok_or_else(|| AiError::Config(format!("repo '{repo_name}' not found")))?;
+
+    Ok(repo)
+}
+
+pub(super) fn git_ctx(ctx: &AppAgentContext) -> AiResult<&GitAgentContext> {
+    ctx.git
+        .as_ref()
+        .ok_or_else(|| AiError::Config("git tools are not available in this session".to_string()))
+}
+
+pub(super) fn rpc_err(status: tonic::Status) -> AiError {
+    AiError::Api(format!("git rpc error: {}", status.message()))
+}
+
+pub(super) fn arg_str<'a>(args: &'a Value, key: &str) -> AiResult<&'a str> {
+    args.get(key)
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| AiError::Config(format!("'{key}' parameter is required")))
+}
+
+pub(super) fn arg_opt_str<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
+    args.get(key).and_then(|v| v.as_str())
+}
+
+pub(super) fn arg_u64(args: &Value, key: &str, default: u64) -> u64 {
+    args.get(key)
+        .and_then(|v| v.as_u64())
+        .unwrap_or(default)
+}
diff --git a/lib/service/agent/git_tools/merge.rs b/lib/service/agent/git_tools/merge.rs
new file mode 100644
index 0000000..1626a5b
--- /dev/null
+++ b/lib/service/agent/git_tools/merge.rs
@@ -0,0 +1,204 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::merge_service_client::MergeServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+pub struct GitMergeBaseTool;
+
+impl GitMergeBaseTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitMergeBaseTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitMergeBaseTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_merge_base" }
+
+    fn description(&self) -> &'static str {
+        "Find the common ancestor (merge base) of two commits."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "oid_a": { "type": "string", "description": "First commit OID" },
+                "oid_b": { "type": "string", "description": "Second commit OID" }
+            },
+            "required": ["workspace", "repo", "oid_a", "oid_b"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let oid_a = arg_str(&args, "oid_a")?;
+        let oid_b = arg_str(&args, "oid_b")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = MergeServiceClient::new(git.channel.clone());
+        let resp = client
+            .merge_base(p::MergeBaseRequest {
+                repo_id: repo.id.to_string(),
+                oid_a: Some(p::ObjectId { value: oid_a.to_string() }),
+                oid_b: Some(p::ObjectId { value: oid_b.to_string() }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        Ok(json!({ "base_oid": resp.base_oid.map(|o| o.value) }))
+    }
+}
+
+pub struct GitMergeAnalysisTool;
+
+impl GitMergeAnalysisTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitMergeAnalysisTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitMergeAnalysisTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_merge_analysis" }
+
+    fn description(&self) -> &'static str {
+        "Analyze whether two commits can be merged (fast-forward, normal, up-to-date, etc)."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "oid_a": { "type": "string", "description": "First commit OID" },
+                "oid_b": { "type": "string", "description": "Second commit OID" }
+            },
+            "required": ["workspace", "repo", "oid_a", "oid_b"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let oid_a = arg_str(&args, "oid_a")?;
+        let oid_b = arg_str(&args, "oid_b")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = MergeServiceClient::new(git.channel.clone());
+        let resp = client
+            .merge_analysis(p::MergeAnalysisRequest {
+                repo_id: repo.id.to_string(),
+                oid_a: Some(p::ObjectId { value: oid_a.to_string() }),
+                oid_b: Some(p::ObjectId { value: oid_b.to_string() }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let analysis = resp.analysis.ok_or_else(|| AiError::Response("no analysis".to_string()))?;
+        let pref = resp.preference.ok_or_else(|| AiError::Response("no preference".to_string()))?;
+
+        // Determine overall status
+        let status = if analysis.is_up_to_date {
+            "up_to_date"
+        } else if analysis.is_fast_forward {
+            "fast_forward"
+        } else if analysis.is_normal {
+            "normal_merge"
+        } else if analysis.is_unborn {
+            "unborn"
+        } else {
+            "none"
+        };
+
+        Ok(json!({
+            "status": status,
+            "analysis": {
+                "is_none": analysis.is_none,
+                "is_normal": analysis.is_normal,
+                "is_up_to_date": analysis.is_up_to_date,
+                "is_fast_forward": analysis.is_fast_forward,
+                "is_unborn": analysis.is_unborn,
+            },
+            "preference": {
+                "is_none": pref.is_none,
+                "is_no_fast_forward": pref.is_no_fast_forward,
+                "is_fastforward_only": pref.is_fastforward_only,
+            },
+        }))
+    }
+}
+
+pub struct GitMergeIsConflictedTool;
+
+impl GitMergeIsConflictedTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitMergeIsConflictedTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitMergeIsConflictedTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_merge_is_conflicted" }
+
+    fn description(&self) -> &'static str {
+        "Check if the repository is currently in a conflicted merge state."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" }
+            },
+            "required": ["workspace", "repo"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = MergeServiceClient::new(git.channel.clone());
+        let resp = client
+            .merge_is_conflicted(p::MergeIsConflictedRequest {
+                repo_id: repo.id.to_string(),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        Ok(json!({ "is_conflicted": resp.is_conflicted }))
+    }
+}
diff --git a/lib/service/agent/git_tools/mod.rs b/lib/service/agent/git_tools/mod.rs
new file mode 100644
index 0000000..e12ffce
--- /dev/null
+++ b/lib/service/agent/git_tools/mod.rs
@@ -0,0 +1,10 @@
+pub mod blame;
+pub mod branch;
+pub mod commit;
+pub mod diff;
+pub mod helpers;
+pub mod merge;
+pub mod tag;
+pub mod tree;
+
+pub use helpers::register_git_tools;
diff --git a/lib/service/agent/git_tools/tag.rs b/lib/service/agent/git_tools/tag.rs
new file mode 100644
index 0000000..81c9960
--- /dev/null
+++ b/lib/service/agent/git_tools/tag.rs
@@ -0,0 +1,243 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::tag_service_client::TagServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, arg_opt_str, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+
+pub struct GitTagListTool;
+
+impl GitTagListTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitTagListTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitTagListTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_tag_list" }
+
+    fn description(&self) -> &'static str { "List all tags in a repository." }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" }
+            },
+            "required": ["workspace", "repo"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = TagServiceClient::new(git.channel.clone());
+        let resp = client
+            .tag_list(p::TagListRequest { repo_id: repo.id.to_string() })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let tags: Vec<Value> = resp.tags.iter().map(|t| json!({
+            "name": t.name,
+            "oid": t.oid.as_ref().map(|o| &o.value),
+            "target": t.target.as_ref().map(|o| &o.value),
+            "is_annotated": t.is_annotated,
+            "message": t.message,
+            "tagger": t.tagger,
+        })).collect();
+
+        Ok(json!({ "tags": tags, "count": tags.len() }))
+    }
+}
+
+
+pub struct GitCreateTagTool;
+
+impl GitCreateTagTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitCreateTagTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitCreateTagTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_create_tag" }
+
+    fn description(&self) -> &'static str { "Create a new tag pointing at a commit." }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "name": { "type": "string", "description": "Tag name" },
+                "target_oid": { "type": "string", "description": "Target commit OID" },
+                "message": { "type": "string", "description": "Tag message (for annotated tags)" },
+                "force": { "type": "boolean", "description": "Force overwrite existing tag" }
+            },
+            "required": ["workspace", "repo", "name", "target_oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let name = arg_str(&args, "name")?;
+        let target_oid = arg_str(&args, "target_oid")?;
+        let message = arg_opt_str(&args, "message").map(String::from);
+        let force = args.get("force").and_then(|v| v.as_bool()).unwrap_or(false);
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = TagServiceClient::new(git.channel.clone());
+        let resp = client
+            .tag_init(p::TagInitRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(p::TagInitParams {
+                    name: name.to_string(),
+                    target: Some(p::ObjectId { value: target_oid.to_string() }),
+                    message,
+                    tagger: None,
+                    force,
+                }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let oid = resp.oid.map(|o| o.value).unwrap_or_default();
+        Ok(json!({ "success": true, "tag": name, "oid": oid }))
+    }
+}
+
+
+pub struct GitTagInfoTool;
+
+impl GitTagInfoTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitTagInfoTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitTagInfoTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_tag_info" }
+
+    fn description(&self) -> &'static str { "Get detailed information about a specific tag." }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "name": { "type": "string", "description": "Tag name" }
+            },
+            "required": ["workspace", "repo", "name"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let name = arg_str(&args, "name")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = TagServiceClient::new(git.channel.clone());
+        let resp = client
+            .tag_info(p::TagInfoRequest { repo_id: repo.id.to_string(), name: name.to_string() })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let t = resp.tag.ok_or_else(|| AiError::Config(format!("tag '{name}' not found")))?;
+        Ok(json!({
+            "name": t.name,
+            "oid": t.oid.as_ref().map(|o| &o.value),
+            "target": t.target.as_ref().map(|o| &o.value),
+            "is_annotated": t.is_annotated,
+            "message": t.message,
+            "tagger": t.tagger,
+            "tagger_email": t.tagger_email,
+        }))
+    }
+}
+
+
+pub struct GitDeleteTagTool;
+
+impl GitDeleteTagTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitDeleteTagTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitDeleteTagTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_delete_tag" }
+
+    fn description(&self) -> &'static str { "Delete a tag from the repository. Requires write access." }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "name": { "type": "string", "description": "Tag name to delete" }
+            },
+            "required": ["workspace", "repo", "name"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let name = arg_str(&args, "name")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut client = TagServiceClient::new(git.channel.clone());
+        client
+            .tag_delete(p::TagDeleteRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(p::TagDeleteParams { name: name.to_string() }),
+            })
+            .await
+            .map_err(rpc_err)?;
+
+        Ok(json!({ "success": true, "tag": name }))
+    }
+}
diff --git a/lib/service/agent/git_tools/tree.rs b/lib/service/agent/git_tools/tree.rs
new file mode 100644
index 0000000..a651caf
--- /dev/null
+++ b/lib/service/agent/git_tools/tree.rs
@@ -0,0 +1,197 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use git::rpc::proto as p;
+use git::rpc::proto::blob_service_client::BlobServiceClient;
+use git::rpc::proto::commit_service_client::CommitServiceClient;
+use git::rpc::proto::tree_service_client::TreeServiceClient;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, arg_opt_str, git_ctx, require_repo_member, rpc_err};
+use crate::agent::run::AppAgentContext;
+
+
+pub struct GitTreeEntriesTool;
+
+impl GitTreeEntriesTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitTreeEntriesTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitTreeEntriesTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_tree_entries" }
+
+    fn description(&self) -> &'static str {
+        "List files and subdirectories at a given path in a commit's tree. Use this to explore repo structure."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "commit_oid": { "type": "string", "description": "Commit OID to read the tree from" },
+                "path": { "type": "string", "description": "Directory path (empty string for root)" }
+            },
+            "required": ["workspace", "repo", "commit_oid"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let commit_oid = arg_str(&args, "commit_oid")?;
+        let path = arg_opt_str(&args, "path").unwrap_or("");
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut commit_client = CommitServiceClient::new(git.channel.clone());
+        let commit_resp = commit_client
+            .commit_info(p::CommitInfoRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: commit_oid.to_string() }),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let tree_oid = commit_resp
+            .commit
+            .and_then(|c| c.tree_id)
+            .ok_or_else(|| AiError::Response("commit has no tree".to_string()))?;
+
+        let mut client = TreeServiceClient::new(git.channel.clone());
+        let resp = client
+            .tree_entries(p::TreeEntriesRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(tree_oid),
+                base_path: path.to_string(),
+                last: false,
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let entries: Vec<Value> = resp.entries.iter().map(|e| {
+            let kind = match p::TreeKind::try_from(e.kind) {
+                Ok(p::TreeKind::Blob) => "file",
+                Ok(p::TreeKind::Tree) => "dir",
+                Ok(p::TreeKind::LfsPointer) => "lfs",
+                _ => "unknown",
+            };
+            json!({
+                "name": e.name,
+                "oid": e.oid.as_ref().map(|o| &o.value),
+                "kind": kind,
+                "is_binary": e.is_binary,
+                "is_lfs": e.is_lfs,
+            })
+        }).collect();
+
+        Ok(json!({ "entries": entries, "count": entries.len() }))
+    }
+}
+
+
+
+pub struct GitFileContentTool;
+
+impl GitFileContentTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for GitFileContentTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for GitFileContentTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "git_file_content" }
+
+    fn description(&self) -> &'static str {
+        "Read the content of a file at a given path from a specific commit. Returns the file content as text."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "repo": { "type": "string", "description": "Repository name" },
+                "commit_oid": { "type": "string", "description": "Commit OID" },
+                "path": { "type": "string", "description": "File path in the repo" }
+            },
+            "required": ["workspace", "repo", "commit_oid", "path"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let repo_name = arg_str(&args, "repo")?;
+        let commit_oid = arg_str(&args, "commit_oid")?;
+        let path = arg_str(&args, "path")?;
+
+        let repo = require_repo_member(git, ctx.user_id, workspace, repo_name).await?;
+
+        let mut tree_client = TreeServiceClient::new(git.channel.clone());
+        let entry_resp = tree_client
+            .tree_entry_by_path_from_commit(p::TreeEntryByPathFromCommitRequest {
+                repo_id: repo.id.to_string(),
+                commit_oid: Some(p::ObjectId { value: commit_oid.to_string() }),
+                path: path.to_string(),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let entry = entry_resp
+            .entry
+            .ok_or_else(|| AiError::Config(format!("file not found: {path}")))?;
+
+        if entry.kind == p::TreeKind::Tree as i32 {
+            return Err(AiError::Config(format!("'{path}' is a directory, not a file")));
+        }
+
+        let blob_oid = entry
+            .oid
+            .ok_or_else(|| AiError::Response("entry has no oid".to_string()))?;
+
+        let mut blob_client = BlobServiceClient::new(git.channel.clone());
+        let blob_resp = blob_client
+            .blob_load(p::BlobLoadRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(blob_oid),
+                path: path.to_string(),
+            })
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let content = String::from_utf8_lossy(&blob_resp.blob).to_string();
+
+        let truncated = content.len() > 64_000;
+        let content = if truncated {
+            format!("{}...(truncated)", &content[..64_000])
+        } else {
+            content
+        };
+
+        Ok(json!({
+            "path": path,
+            "content": content,
+            "size": blob_resp.blob.len(),
+            "truncated": truncated,
+        }))
+    }
+}
diff --git a/lib/service/agent/issue_tools/helpers.rs b/lib/service/agent/issue_tools/helpers.rs
new file mode 100644
index 0000000..b6e835d
--- /dev/null
+++ b/lib/service/agent/issue_tools/helpers.rs
@@ -0,0 +1,59 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::register::ToolRegister;
+use db::sqlx;
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::agent::run::{AppAgentContext, GitAgentContext};
+
+pub fn register_issue_tools(tools: &mut ToolRegister<AppAgentContext>) {
+    tools.register(super::issue::IssueListTool::new());
+    tools.register(super::issue::IssueGetTool::new());
+    tools.register(super::issue::IssueCommentsTool::new());
+    tools.register(super::issue::IssueEventsTool::new());
+}
+
+pub(super) async fn require_workspace_member(
+    git: &GitAgentContext,
+    user_id: Uuid,
+    workspace_name: &str,
+) -> AiResult<Uuid> {
+    let wk_id: Uuid = sqlx::query_scalar(
+        "SELECT id FROM workspace WHERE name = $1",
+    )
+    .bind(workspace_name)
+    .fetch_optional(git.db.reader())
+    .await
+    .map_err(AiError::Database)?
+    .ok_or_else(|| AiError::Config(format!("workspace '{workspace_name}' not found")))?;
+
+    let is_member: i64 = sqlx::query_scalar(
+        "SELECT COUNT(*) FROM wk_member \
+         WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+    )
+    .bind(wk_id)
+    .bind(user_id)
+    .fetch_one(git.db.reader())
+    .await
+    .map_err(AiError::Database)?;
+
+    if is_member == 0 {
+        return Err(AiError::Config(format!(
+            "user is not a member of workspace '{workspace_name}'"
+        )));
+    }
+
+    Ok(wk_id)
+}
+
+pub(super) fn git_ctx(ctx: &AppAgentContext) -> AiResult<&GitAgentContext> {
+    ctx.git
+        .as_ref()
+        .ok_or_else(|| AiError::Config("issue tools are not available in this session".to_string()))
+}
+
+pub(super) fn arg_str<'a>(args: &'a Value, key: &str) -> AiResult<&'a str> {
+    args.get(key)
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| AiError::Config(format!("'{key}' parameter is required")))
+}
diff --git a/lib/service/agent/issue_tools/issue.rs b/lib/service/agent/issue_tools/issue.rs
new file mode 100644
index 0000000..6cb3769
--- /dev/null
+++ b/lib/service/agent/issue_tools/issue.rs
@@ -0,0 +1,353 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use db::sqlx;
+use serde_json::{json, Value};
+
+use super::helpers::{arg_str, git_ctx, require_workspace_member};
+use crate::agent::run::AppAgentContext;
+
+pub struct IssueListTool;
+
+impl IssueListTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for IssueListTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for IssueListTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "issue_list" }
+
+    fn description(&self) -> &'static str {
+        "List issues in a workspace with optional filters: state (open/closed), priority, label, milestone, assignee."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "state": { "type": "string", "description": "Filter by state: 'open' or 'closed'" },
+                "priority": { "type": "string", "description": "Filter by priority" },
+                "label": { "type": "string", "description": "Filter by label name" },
+                "milestone": { "type": "string", "description": "Filter by milestone title" },
+                "assignee": { "type": "string", "description": "Filter by assignee username" },
+                "limit": { "type": "integer", "description": "Max results (default 20, max 100)" }
+            },
+            "required": ["workspace"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+        let limit = args.get("limit").and_then(|v| v.as_i64()).unwrap_or(20).min(100);
+
+        let mut conditions = vec!["i.wk = $1".to_string(), "i.deleted_at IS NULL".to_string()];
+        let mut params: Vec<String> = vec![wk_id.to_string()];
+        let mut idx = 2i32;
+
+        for (arg, col) in [
+            ("state", "i.state"),
+            ("priority", "i.priority"),
+        ] {
+            if let Some(v) = args.get(arg).and_then(|v| v.as_str()).filter(|s| !s.is_empty()) {
+                conditions.push(format!("{col} = ${idx}"));
+                params.push(v.to_string());
+                idx += 1;
+            }
+        }
+
+        if let Some(v) = args.get("label").and_then(|v| v.as_str()).filter(|s| !s.is_empty()) {
+            conditions.push(format!("EXISTS(SELECT 1 FROM issue_label il INNER JOIN label l ON l.id = il.label WHERE il.issue = i.id AND l.name = ${idx})"));
+            params.push(v.to_string());
+            idx += 1;
+        }
+
+        if let Some(v) = args.get("milestone").and_then(|v| v.as_str()).filter(|s| !s.is_empty()) {
+            conditions.push(format!("EXISTS(SELECT 1 FROM issue_milestone im INNER JOIN milestone m ON m.id = im.milestone WHERE im.issue = i.id AND m.title = ${idx})"));
+            params.push(v.to_string());
+            idx += 1;
+        }
+
+        if let Some(v) = args.get("assignee").and_then(|v| v.as_str()).filter(|s| !s.is_empty()) {
+            conditions.push(format!("EXISTS(SELECT 1 FROM issue_assignee ia INNER JOIN \"user\" u ON u.id = ia.\"user\" WHERE ia.issue = i.id AND u.username = ${idx})"));
+            params.push(v.to_string());
+            idx += 1;
+        }
+
+        let where_clause = conditions.join(" AND ");
+        let query = format!(
+            "SELECT i.number, i.title, i.body, i.state, i.priority, \
+             i.closed_at, i.due_at, i.created_at \
+             FROM issue i WHERE {where_clause} \
+             ORDER BY i.created_at DESC LIMIT ${idx}",
+        );
+
+        let mut q = sqlx::query_as::<_, IssueRow>(db::sqlx::AssertSqlSafe(query));
+        q = q.bind(wk_id);
+        for i in 1..params.len() {
+            q = q.bind(&params[i]);
+        }
+        q = q.bind(limit);
+
+        let rows = q.fetch_all(git.db.reader()).await.map_err(AiError::Database)?;
+
+        let issues: Vec<Value> = rows.iter().map(|r| json!({
+            "number": r.number,
+            "title": r.title,
+            "state": r.state,
+            "priority": r.priority,
+            "body": r.body.as_ref().map(|b| if b.len() > 500 { format!("{}...", &b[..500]) } else { b.clone() }),
+            "created_at": r.created_at.to_rfc3339(),
+        })).collect();
+
+        Ok(json!({ "issues": issues, "count": issues.len() }))
+    }
+}
+
+#[derive(sqlx::FromRow)]
+struct IssueRow {
+    number: i64,
+    title: String,
+    body: Option<String>,
+    state: String,
+    priority: String,
+    due_at: Option<chrono::DateTime<chrono::Utc>>,
+    closed_at: Option<chrono::DateTime<chrono::Utc>>,
+    created_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub struct IssueGetTool;
+
+impl IssueGetTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for IssueGetTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for IssueGetTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "issue_get" }
+
+    fn description(&self) -> &'static str {
+        "Get full details of a single issue by its number."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "number": { "type": "integer", "description": "Issue number" }
+            },
+            "required": ["workspace", "number"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let number = args.get("number").and_then(|v| v.as_i64())
+            .ok_or_else(|| AiError::Config("'number' parameter is required".to_string()))?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+
+        let row = sqlx::query_as::<_, IssueRow>(
+            "SELECT number, title, body, state, priority, \
+             closed_at, due_at, created_at \
+             FROM issue WHERE wk = $1 AND number = $2 AND deleted_at IS NULL",
+        )
+        .bind(wk_id)
+        .bind(number)
+        .fetch_optional(git.db.reader())
+        .await
+        .map_err(AiError::Database)?
+        .ok_or_else(|| AiError::Config(format!("issue #{number} not found")))?;
+
+        // Load labels
+        #[derive(sqlx::FromRow)]
+        struct LabelRow { name: String }
+
+        let labels: Vec<String> = sqlx::query_as::<_, LabelRow>(
+            "SELECT l.name FROM label l \
+             INNER JOIN issue_label il ON il.label = l.id \
+             WHERE il.issue = (SELECT id FROM issue WHERE wk = $1 AND number = $2)",
+        )
+        .bind(wk_id).bind(number)
+        .fetch_all(git.db.reader()).await.map_err(AiError::Database)?
+        .iter().map(|r| r.name.clone()).collect();
+
+        // Load assignees
+        #[derive(sqlx::FromRow)]
+        struct AssigneeRow { username: String }
+
+        let assignees: Vec<String> = sqlx::query_as::<_, AssigneeRow>(
+            "SELECT u.username FROM \"user\" u \
+             INNER JOIN issue_assignee ia ON ia.\"user\" = u.id \
+             WHERE ia.issue = (SELECT id FROM issue WHERE wk = $1 AND number = $2)",
+        )
+        .bind(wk_id).bind(number)
+        .fetch_all(git.db.reader()).await.map_err(AiError::Database)?
+        .iter().map(|r| r.username.clone()).collect();
+
+        Ok(json!({
+            "number": row.number,
+            "title": row.title,
+            "body": row.body,
+            "state": row.state,
+            "priority": row.priority,
+            "labels": labels,
+            "assignees": assignees,
+            "created_at": row.created_at.to_rfc3339(),
+            "due_at": row.due_at.map(|d| d.to_rfc3339()),
+            "closed_at": row.closed_at.map(|d| d.to_rfc3339()),
+        }))
+    }
+}
+
+pub struct IssueCommentsTool;
+
+impl IssueCommentsTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for IssueCommentsTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for IssueCommentsTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "issue_comments" }
+
+    fn description(&self) -> &'static str {
+        "List comments on an issue, ordered by time."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "number": { "type": "integer", "description": "Issue number" },
+                "limit": { "type": "integer", "description": "Max results (default 50)" }
+            },
+            "required": ["workspace", "number"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let number = args.get("number").and_then(|v| v.as_i64())
+            .ok_or_else(|| AiError::Config("'number' parameter is required".to_string()))?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+        let limit = args.get("limit").and_then(|v| v.as_i64()).unwrap_or(50).min(200);
+
+        #[derive(sqlx::FromRow)]
+        struct CommentRow {
+            body: String,
+            username: String,
+            created_at: chrono::DateTime<chrono::Utc>,
+        }
+
+        let rows: Vec<CommentRow> = sqlx::query_as(
+            "SELECT ic.body, u.username, ic.created_at \
+             FROM issue_comment ic \
+             INNER JOIN \"user\" u ON u.id = ic.author \
+             WHERE ic.issue = (SELECT id FROM issue WHERE wk = $1 AND number = $2) \
+               AND ic.deleted_at IS NULL \
+             ORDER BY ic.created_at ASC LIMIT $3",
+        )
+        .bind(wk_id).bind(number).bind(limit)
+        .fetch_all(git.db.reader()).await.map_err(AiError::Database)?;
+
+        let comments: Vec<Value> = rows.iter().map(|r| json!({
+            "author": r.username,
+            "body": r.body,
+            "created_at": r.created_at.to_rfc3339(),
+        })).collect();
+
+        Ok(json!({ "issue_number": number, "comments": comments, "count": comments.len() }))
+    }
+}
+
+pub struct IssueEventsTool;
+
+impl IssueEventsTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for IssueEventsTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for IssueEventsTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "issue_events" }
+
+    fn description(&self) -> &'static str {
+        "List the timeline of events for an issue (created, commented, closed, labeled, etc)."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "number": { "type": "integer", "description": "Issue number" }
+            },
+            "required": ["workspace", "number"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let number = args.get("number").and_then(|v| v.as_i64())
+            .ok_or_else(|| AiError::Config("'number' parameter is required".to_string()))?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+
+        #[derive(sqlx::FromRow)]
+        struct EventRow {
+            event: String,
+            from_value: Option<String>,
+            to_value: Option<String>,
+            username: Option<String>,
+            created_at: chrono::DateTime<chrono::Utc>,
+        }
+
+        let rows: Vec<EventRow> = sqlx::query_as(
+            "SELECT e.event, e.from_value, e.to_value, u.username, e.created_at \
+             FROM issue_event e \
+             LEFT JOIN \"user\" u ON u.id = e.actor \
+             WHERE e.issue = (SELECT id FROM issue WHERE wk = $1 AND number = $2) \
+             ORDER BY e.created_at ASC",
+        )
+        .bind(wk_id).bind(number)
+        .fetch_all(git.db.reader()).await.map_err(AiError::Database)?;
+
+        let events: Vec<Value> = rows.iter().map(|r| json!({
+            "event": r.event,
+            "actor": r.username,
+            "from": r.from_value,
+            "to": r.to_value,
+            "created_at": r.created_at.to_rfc3339(),
+        })).collect();
+
+        Ok(json!({ "issue_number": number, "events": events, "count": events.len() }))
+    }
+}
diff --git a/lib/service/agent/issue_tools/mod.rs b/lib/service/agent/issue_tools/mod.rs
new file mode 100644
index 0000000..bcf33ae
--- /dev/null
+++ b/lib/service/agent/issue_tools/mod.rs
@@ -0,0 +1,4 @@
+pub mod helpers;
+pub mod issue;
+
+pub use helpers::register_issue_tools;
diff --git a/lib/service/agent/memory.rs b/lib/service/agent/memory.rs
new file mode 100644
index 0000000..91da680
--- /dev/null
+++ b/lib/service/agent/memory.rs
@@ -0,0 +1,246 @@
+use ai::{
+    error::{AiError, AiResult},
+    tool::tools::FunctionCall,
+};
+use async_trait::async_trait;
+use chrono::Utc;
+use db::sqlx;
+use serde_json::{json, Value};
+use tracing::info;
+use uuid::Uuid;
+
+use super::run::AppAgentContext;
+use crate::error::AppError;
+use crate::AppService;
+pub struct SaveMemoryTool;
+
+impl SaveMemoryTool {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for SaveMemoryTool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl FunctionCall for SaveMemoryTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str {
+        "save_memory"
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "description": "A short, descriptive key for the memory (e.g. 'user_preference_language', 'project_architecture')"
+                },
+                "value": {
+                    "type": "string",
+                    "description": "The information to remember"
+                },
+                "importance": {
+                    "type": "integer",
+                    "description": "Importance level 0-10 (10 = most important). Default: 5",
+                    "minimum": 0,
+                    "maximum": 10
+                }
+            },
+            "required": ["key", "value"]
+        })
+    }
+
+    async fn call(
+        &self,
+        context: &mut Self::Context,
+        args: Value,
+    ) -> AiResult<Value> {
+        let key = args
+            .get("key")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| AiError::Config("key parameter is required".to_string()))?;
+
+        let value = args
+            .get("value")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| AiError::Config("value parameter is required".to_string()))?;
+
+        let importance = args
+            .get("importance")
+            .and_then(|v| v.as_i64())
+            .unwrap_or(5)
+            .clamp(0, 10) as i32;
+
+        context.pending_memories.push(PendingMemory {
+            key: key.to_string(),
+            value: value.to_string(),
+            importance,
+        });
+
+        Ok(json!({
+            "success": true,
+            "key": key,
+            "message": format!("Memory '{}' saved (importance: {})", key, importance)
+        }))
+    }
+}
+pub struct RecallMemoryTool {
+    memories_json: String,
+}
+
+impl RecallMemoryTool {
+    pub fn new(memories_json: String) -> Self {
+        Self { memories_json }
+    }
+}
+
+#[async_trait]
+impl FunctionCall for RecallMemoryTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str {
+        "recall_memory"
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Optional search query to filter memories by key or content"
+                }
+            }
+        })
+    }
+
+    async fn call(
+        &self,
+        _context: &mut Self::Context,
+        args: Value,
+    ) -> AiResult<Value> {
+        let query = args
+            .get("query")
+            .and_then(|v| v.as_str())
+            .unwrap_or("");
+
+        if query.is_empty() {
+            return Ok(json!({
+                "memories": self.memories_json,
+                "count": "all"
+            }));
+        }
+
+        Ok(json!({
+            "memories": self.memories_json,
+            "query": query,
+            "hint": "Search the memories above for matches to your query"
+        }))
+    }
+}
+#[derive(Debug, Clone)]
+pub struct PendingMemory {
+    pub key: String,
+    pub value: String,
+    pub importance: i32,
+}
+
+impl AppService {
+    pub(crate) async fn agent_load_memories(
+        &self,
+        session_id: Uuid,
+    ) -> Result<(String, Vec<(Uuid, String, String, i32)>), AppError> {
+        let rows: Vec<(Uuid, String, String, i32)> = sqlx::query_as(
+            "SELECT id, key, value, importance \
+             FROM agent_long_term_memory \
+             WHERE session = $1 AND deleted_at IS NULL \
+             ORDER BY importance DESC, updated_at DESC \
+             LIMIT 50",
+        )
+        .bind(session_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if rows.is_empty() {
+            return Ok((String::new(), rows));
+        }
+
+        let mut formatted = String::from("Long-term memories for this session:\n");
+        for (_, key, value, importance) in &rows {
+            formatted.push_str(&format!(
+                "- [{}] {} (importance: {})\n",
+                key, value, importance
+            ));
+        }
+
+        Ok((formatted, rows))
+    }
+    pub(crate) async fn agent_persist_memories(
+        &self,
+        session_id: Uuid,
+        memories: &[PendingMemory],
+    ) -> Result<(), AppError> {
+        if memories.is_empty() {
+            return Ok(());
+        }
+
+        let now = Utc::now();
+        for mem in memories {
+            sqlx::query(
+                "INSERT INTO agent_long_term_memory \
+                 (id, session, key, value, importance, created_at, updated_at) \
+                 VALUES ($1, $2, $3, $4, $5, $6, $6) \
+                 ON CONFLICT (session, key) WHERE deleted_at IS NULL \
+                 DO UPDATE SET value = $4, importance = $5, updated_at = $6",
+            )
+            .bind(Uuid::now_v7())
+            .bind(session_id)
+            .bind(&mem.key)
+            .bind(&mem.value)
+            .bind(mem.importance)
+            .bind(now)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        info!(
+            session_id = %session_id,
+            count = memories.len(),
+            "persisted long-term memories from agent run"
+        );
+
+        Ok(())
+    }
+    #[allow(dead_code)]
+    pub(crate) async fn agent_touch_memories(
+        &self,
+        memory_ids: &[Uuid],
+    ) -> Result<(), AppError> {
+        if memory_ids.is_empty() {
+            return Ok(());
+        }
+
+        let now = Utc::now();
+        sqlx::query(
+            "UPDATE agent_long_term_memory \
+             SET last_used_at = $1 \
+             WHERE id = ANY($2::uuid[])",
+        )
+        .bind(now)
+        .bind(memory_ids)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+}
diff --git a/lib/service/agent/memory_provider.rs b/lib/service/agent/memory_provider.rs
new file mode 100644
index 0000000..686a7d1
--- /dev/null
+++ b/lib/service/agent/memory_provider.rs
@@ -0,0 +1,168 @@
+use ai::error::AiResult;
+use ai::memory::{MemoryEntry, MemoryProvider};
+use async_trait::async_trait;
+use chrono::Utc;
+use db::sqlx;
+use uuid::Uuid;
+#[derive(Clone)]
+pub struct SimpleMemoryProvider {
+    db: db::AppDatabase,
+}
+
+impl SimpleMemoryProvider {
+    pub fn new(db: db::AppDatabase) -> Self {
+        Self { db }
+    }
+}
+
+#[async_trait]
+impl MemoryProvider for SimpleMemoryProvider {
+    fn name(&self) -> &'static str {
+        "simple"
+    }
+
+    async fn save(
+        &self,
+        session_id: Uuid,
+        key: &str,
+        value: &str,
+        importance: i32,
+    ) -> AiResult<()> {
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_long_term_memory \
+             (id, session, key, value, importance, last_used_at, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $6, $6) \
+             ON CONFLICT ON CONSTRAINT idx_agent_ltm_session_key \
+             DO UPDATE SET value = $4, importance = $5, last_used_at = $6, updated_at = $6",
+        )
+        .bind(Uuid::now_v7())
+        .bind(session_id)
+        .bind(key)
+        .bind(value)
+        .bind(importance)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| {
+            ai::error::AiError::Response(format!("memory save error: {e}"))
+        })?;
+
+        Ok(())
+    }
+
+    async fn recall(
+        &self,
+        session_id: Uuid,
+        query: &str,
+        limit: usize,
+    ) -> AiResult<Vec<MemoryEntry>> {
+        use db::sqlx::FromRow;
+
+        #[derive(Debug, FromRow)]
+        struct Row {
+            key: String,
+            value: String,
+            importance: i32,
+            last_used_at: Option<chrono::DateTime<Utc>>,
+        }
+
+        let rows: Vec<Row> = sqlx::query_as(
+            "SELECT key, value, importance, last_used_at \
+             FROM agent_long_term_memory \
+             WHERE session = $1 \
+               AND deleted_at IS NULL \
+               AND (value ILIKE $2 OR key ILIKE $2) \
+             ORDER BY importance DESC, last_used_at DESC NULLS LAST \
+             LIMIT $3",
+        )
+        .bind(session_id)
+        .bind(format!("%{query}%"))
+        .bind(limit as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| {
+            ai::error::AiError::Response(format!("memory recall error: {e}"))
+        })?;
+
+        let entries: Vec<MemoryEntry> = rows
+            .into_iter()
+            .map(|r| MemoryEntry {
+                key: r.key,
+                value: r.value,
+                importance: r.importance,
+                last_used_at: r.last_used_at.map(|dt| dt.to_rfc3339()),
+            })
+            .collect();
+        if !entries.is_empty() {
+            let now = Utc::now();
+            let _ = sqlx::query(
+                "UPDATE agent_long_term_memory \
+                 SET last_used_at = $1, updated_at = $1 \
+                 WHERE session = $2 AND value ILIKE $3 AND deleted_at IS NULL",
+            )
+            .bind(now)
+            .bind(session_id)
+            .bind(format!("%{query}%"))
+            .execute(self.db.writer())
+            .await;
+        }
+
+        Ok(entries)
+    }
+
+    async fn forget(&self, session_id: Uuid, key: &str) -> AiResult<()> {
+        let now = Utc::now();
+        sqlx::query(
+            "UPDATE agent_long_term_memory \
+             SET deleted_at = $1, updated_at = $1 \
+             WHERE session = $2 AND key = $3 AND deleted_at IS NULL",
+        )
+        .bind(now)
+        .bind(session_id)
+        .bind(key)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| {
+            ai::error::AiError::Response(format!("memory forget error: {e}"))
+        })?;
+
+        Ok(())
+    }
+
+    async fn build_context_block(&self, session_id: Uuid) -> AiResult<String> {
+        use db::sqlx::FromRow;
+
+        #[derive(Debug, FromRow)]
+        struct Entry {
+            key: String,
+            value: String,
+        }
+
+        let rows: Vec<Entry> = sqlx::query_as(
+            "SELECT key, value \
+             FROM agent_long_term_memory \
+             WHERE session = $1 AND deleted_at IS NULL \
+             ORDER BY importance DESC, last_used_at DESC NULLS LAST \
+             LIMIT 20",
+        )
+        .bind(session_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| {
+            ai::error::AiError::Response(format!("memory context error: {e}"))
+        })?;
+
+        if rows.is_empty() {
+            return Ok(String::new());
+        }
+
+        let mut block = String::from("<user_memories>\n");
+        for row in &rows {
+            block.push_str(&format!("- {}: {}\n", row.key, row.value));
+        }
+        block.push_str("</user_memories>");
+
+        Ok(block)
+    }
+}
diff --git a/lib/service/agent/mod.rs b/lib/service/agent/mod.rs
new file mode 100644
index 0000000..77a66c0
--- /dev/null
+++ b/lib/service/agent/mod.rs
@@ -0,0 +1,17 @@
+pub mod billing;
+pub mod compaction;
+pub mod config;
+pub mod context;
+pub mod conversation;
+pub mod git_tools;
+pub mod issue_tools;
+pub mod memory;
+pub mod memory_provider;
+pub mod persistence;
+pub mod run;
+pub mod session;
+pub mod sse;
+pub mod tools;
+pub mod trace;
+pub mod types;
+pub mod workspace_tools;
diff --git a/lib/service/agent/persistence.rs b/lib/service/agent/persistence.rs
new file mode 100644
index 0000000..8429b40
--- /dev/null
+++ b/lib/service/agent/persistence.rs
@@ -0,0 +1,194 @@
+use chrono::Utc;
+use db::sqlx;
+use uuid::Uuid;
+
+use super::types::{AgentCostInfo, AgentStepInfo, AgentToolCallInfo, BillingRecord, SessionContext};
+use crate::error::AppError;
+use crate::AppService;
+
+impl AppService {
+    pub(super) async fn persist_user_message(
+        &self,
+        conversation_id: Uuid,
+        user_id: Uuid,
+        content: &str,
+    ) -> Result<Uuid, AppError> {
+        let message_id = Uuid::now_v7();
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_message \
+             (id, conversation, role, author, content, content_type, status, created_at, updated_at) \
+             VALUES ($1, $2, 'user', $3, $4, 'text', 'completed', $5, $5)",
+        )
+        .bind(message_id)
+        .bind(conversation_id)
+        .bind(user_id)
+        .bind(content)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(message_id)
+    }
+
+    pub(super) async fn persist_assistant_message(
+        &self,
+        conversation_id: Uuid,
+        _session_id: Uuid,
+        content: &str,
+        reasoning_content: Option<&str>,
+        invocation_id: Uuid,
+    ) -> Result<Uuid, AppError> {
+        let message_id = Uuid::now_v7();
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_message \
+             (id, conversation, role, content, content_type, status, \
+              model_invocation, reasoning_content, created_at, updated_at) \
+             VALUES ($1, $2, 'assistant', $3, 'text', 'completed', $4, $5, $6, $6)",
+        )
+        .bind(message_id)
+        .bind(conversation_id)
+        .bind(content)
+        .bind(invocation_id)
+        .bind(reasoning_content)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(message_id)
+    }
+
+    pub(super) async fn persist_billing_and_deduct(
+        &self,
+        ctx: &SessionContext,
+        invocation_id: Uuid,
+        input_tokens: i64,
+        output_tokens: i64,
+    ) -> Result<Option<AgentCostInfo>, AppError> {
+        let cost_result = self
+            .agent_calculate_cost(ctx.model_version_id, input_tokens, output_tokens)
+            .await?;
+
+        let (cost, currency) = match cost_result {
+            Some((c, cur)) => (c, cur),
+            None => {
+                let record = BillingRecord {
+                    invocation_id,
+                    session_id: ctx.session_id,
+                    model_version_id: ctx.model_version_id,
+                    input_tokens,
+                    output_tokens,
+                    cached_input_tokens: 0,
+                    cache_read_tokens: 0,
+                    cache_write_tokens: 0,
+                    reasoning_tokens: 0,
+                    total_tokens: input_tokens.saturating_add(output_tokens),
+                    cost: None,
+                    currency: None,
+                    created_at: Utc::now(),
+                };
+                self.agent_record_usage(&record).await?;
+                return Ok(None);
+            }
+        };
+
+        let record = BillingRecord {
+            invocation_id,
+            session_id: ctx.session_id,
+            model_version_id: ctx.model_version_id,
+            input_tokens,
+            output_tokens,
+            cached_input_tokens: 0,
+            cache_read_tokens: 0,
+            cache_write_tokens: 0,
+            reasoning_tokens: 0,
+            total_tokens: input_tokens.saturating_add(output_tokens),
+            cost: Some(cost),
+            currency: Some(currency.clone()),
+            created_at: Utc::now(),
+        };
+        self.agent_record_usage(&record).await?;
+
+        if let Err(e) = self.agent_deduct_billing(ctx, cost).await {
+            tracing::warn!(
+                invocation_id = %invocation_id,
+                error = %e,
+                "agent billing deduction failed"
+            );
+        }
+
+        Ok(Some(AgentCostInfo {
+            amount: cost.to_string(),
+            currency,
+        }))
+    }
+
+    pub(super) async fn update_conversation_timestamp(
+        &self,
+        conversation_id: Uuid,
+    ) -> Result<(), AppError> {
+        let now = Utc::now();
+        sqlx::query(
+            "UPDATE agent_conversation SET last_message_at = $1, updated_at = $1 WHERE id = $2",
+        )
+        .bind(now)
+        .bind(conversation_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+
+    pub(super) async fn update_conversation_title(
+        &self,
+        conversation_id: Uuid,
+        title: &str,
+    ) -> Result<(), AppError> {
+        let now = Utc::now();
+        sqlx::query(
+            "UPDATE agent_conversation SET title = $1, updated_at = $2 WHERE id = $3",
+        )
+        .bind(title)
+        .bind(now)
+        .bind(conversation_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+}
+
+#[allow(dead_code)]
+pub(super) fn step_info_from_agent(step: ai::agent::AgentStep) -> AgentStepInfo {
+    AgentStepInfo {
+        index: step.index,
+        assistant: step.assistant,
+        tool_calls: step
+            .tool_calls
+            .into_iter()
+            .map(tool_call_info_from_record)
+            .collect(),
+        reflection: step.reflection,
+    }
+}
+
+#[allow(dead_code)]
+pub(super) fn tool_call_info_from_record(record: ai::agent::ToolCallRecord) -> AgentToolCallInfo {
+    AgentToolCallInfo {
+        id: record.id,
+        name: record.name,
+        arguments: record.arguments,
+        output: record.output,
+        error: record.error,
+        elapsed_ms: record.elapsed_ms,
+    }
+}
+
+pub(super) fn stream_error(error: &str) -> String {
+    let payload = serde_json::json!({
+        "type": "error",
+        "error": error,
+    });
+    format!("data: {}\n\n", payload)
+}
diff --git a/lib/service/agent/run.rs b/lib/service/agent/run.rs
new file mode 100644
index 0000000..1c17ff3
--- /dev/null
+++ b/lib/service/agent/run.rs
@@ -0,0 +1,283 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use ai::{
+    agent::RigAgent,
+    tool::register::ToolRegister,
+};
+use cache::AppCache;
+use db::AppDatabase;
+use tonic::transport::Channel;
+use tracing::{info, warn};
+use uuid::Uuid;
+
+use super::types::{
+    AgentRunRequest, AgentRunResponse, AgentUsageInfo,
+};
+use crate::error::AppError;
+use crate::AppService;
+
+#[derive(Clone)]
+pub struct GitAgentContext {
+    pub channel: Channel,
+    pub db: AppDatabase,
+    pub cache: AppCache,
+}
+
+#[derive(Clone)]
+pub struct AppAgentContext {
+    pub user_id: Uuid,
+    pub session_id: Uuid,
+    pub conversation_id: Uuid,
+    pub pending_title: Option<String>,
+    pub pending_memories: Vec<super::memory::PendingMemory>,
+    pub git: Option<GitAgentContext>,
+}
+
+impl AppService {
+    pub async fn agent_run(
+        &self,
+        user_id: Uuid,
+        req: AgentRunRequest,
+    ) -> Result<AgentRunResponse, AppError> {
+        let ctx = self.agent_session_context(req.session_id, user_id).await?;
+
+        let conversation_id = req
+            .conversation_id
+            .ok_or_else(|| AppError::BadRequest("conversation_id is required".to_string()))?;
+        let conversation = self
+            .agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+        if conversation.session != ctx.session_id {
+            return Err(AppError::BadRequest(
+                "conversation does not belong to session".to_string(),
+            ));
+        }
+
+        let ai_client = self
+            .agent_build_ai_client(ctx.model_version_id)
+            .await?;
+
+        let agent_config = self.agent_build_config(
+            &ctx,
+            req.max_steps,
+        );
+
+        self.agent_maybe_compact(&ai_client, &ctx.provider_model_name, conversation_id)
+            .await
+            .unwrap_or_else(|e| {
+                warn!(error = %e, "compaction check failed, continuing");
+            });
+
+        let mut tools: ToolRegister<AppAgentContext> = ToolRegister::new();
+        if conversation.title == "New Chat" || conversation.title.trim().is_empty() {
+            tools.register(super::tools::SetTitleTool::new());
+        }
+        tools.register(super::memory::SaveMemoryTool::new());
+
+        let (memories_text, _memory_rows) =
+            self.agent_load_memories(ctx.session_id).await?;
+        if !memories_text.is_empty() {
+            tools.register(super::memory::RecallMemoryTool::new(memories_text));
+        }
+
+        super::git_tools::register_git_tools(&mut tools);
+        super::workspace_tools::register_workspace_tools(&mut tools);
+        super::issue_tools::register_issue_tools(&mut tools);
+
+        let agent_ctx = AppAgentContext {
+            user_id,
+            session_id: ctx.session_id,
+            conversation_id,
+            pending_title: None,
+            pending_memories: Vec::new(),
+            git: Some(GitAgentContext {
+                channel: self.git.clone(),
+                db: self.db.clone(),
+                cache: self.cache.clone(),
+            }),
+        };
+
+        let shared_ctx = Arc::new(tokio::sync::Mutex::new(agent_ctx));
+        let mut tool_set = ai::agent::RigToolSet::from_register(&tools, shared_ctx);
+        let rig_tools = tool_set.take_tools();
+
+        let agent = RigAgent::new(ai_client.clone(), agent_config)
+            .map_err(|e| AppError::AiError(e))?;
+
+        let timeout_secs = req.timeout_secs.unwrap_or(300);
+
+        let agent_request = self
+            .agent_build_request(
+                &ai_client,
+                &ctx,
+                req.conversation_id,
+                req.input.clone(),
+                Some(timeout_secs),
+            )
+            .await?;
+
+        let invocation_id = Uuid::now_v7();
+        info!(
+            invocation_id = %invocation_id,
+            session_id = %ctx.session_id,
+            user_id = %user_id,
+            billing_target = ?ctx.billing_target,
+            "agent run starting"
+        );
+
+        let user_message_id = self
+            .persist_user_message(conversation_id, user_id, &req.input)
+            .await?;
+        let result = match tokio::time::timeout(
+            Duration::from_secs(timeout_secs),
+            agent.chat(agent_request, rig_tools),
+        )
+        .await
+        {
+            Ok(Ok(output)) => Ok(output),
+            Ok(Err(e)) => Err(e),
+            Err(_) => Err(ai::error::AiError::Timeout {
+                seconds: timeout_secs,
+            }),
+        };
+
+        let agent_ctx = tool_set.into_context();
+
+        match result {
+            Ok(output) => {
+                let message_id = self
+                    .persist_assistant_message(
+                        conversation_id,
+                        ctx.session_id,
+                        &output,
+                        None,
+                        invocation_id,
+                    )
+                    .await?;
+
+                let cost_info =
+                    self.persist_billing_and_deduct(
+                        &ctx,
+                        invocation_id,
+                        0, // input_tokens not tracked in chat() mode
+                        0, // output_tokens not tracked in chat() mode
+                    )
+                    .await?;
+
+                self.agent_record_invocation(
+                    invocation_id,
+                    ctx.session_id,
+                    Some(conversation_id),
+                    Some(message_id),
+                    ctx.model_version_id,
+                    "completed",
+                    None,
+                )
+                .await?;
+
+                self.update_conversation_timestamp(conversation_id)
+                    .await?;
+
+                let title = agent_ctx
+                    .pending_title
+                    .filter(|t| !t.trim().is_empty())
+                    .or_else(|| {
+                        let first_line =
+                            req.input.lines().next().unwrap_or(&req.input);
+                        let truncated: String =
+                            first_line.chars().take(50).collect();
+                        if truncated.trim().is_empty() {
+                            None
+                        } else if first_line.len() > 50 {
+                            Some(format!("{}…", truncated.trim_end()))
+                        } else {
+                            Some(truncated.trim().to_string())
+                        }
+                    });
+
+                if let Some(new_title) = &title {
+                    if let Err(e) = self
+                        .update_conversation_title(
+                            conversation_id,
+                            new_title,
+                        )
+                        .await
+                    {
+                        warn!(
+                            conversation_id = %conversation_id,
+                            error = %e,
+                            "failed to update conversation title"
+                        );
+                    }
+                }
+
+                if let Err(e) = self
+                    .agent_persist_memories(
+                        ctx.session_id,
+                        &agent_ctx.pending_memories,
+                    )
+                    .await
+                {
+                    warn!(
+                        invocation_id = %invocation_id,
+                        error = %e,
+                        "failed to persist agent memories"
+                    );
+                }
+
+                info!(
+                    invocation_id = %invocation_id,
+                    message_id = %message_id,
+                    "agent run completed successfully"
+                );
+
+                Ok(AgentRunResponse {
+                    message_id,
+                    conversation_id,
+                    output,
+                    steps: Vec::new(),
+                    usage: AgentUsageInfo {
+                        input_tokens: 0,
+                        output_tokens: 0,
+                        total_tokens: 0,
+                    },
+                    cost: cost_info,
+                })
+            }
+            Err(e) => {
+                warn!(
+                    invocation_id = %invocation_id,
+                    error = %e,
+                    "agent run failed"
+                );
+
+                let error_content = format!(
+                    "I encountered an error while processing your request: {e}"
+                );
+                let _ = self
+                    .persist_assistant_message(
+                        conversation_id,
+                        ctx.session_id,
+                        &error_content,
+                        None,
+                        invocation_id,
+                    )
+                    .await;
+
+                self.agent_record_invocation(
+                    invocation_id,
+                    ctx.session_id,
+                    Some(conversation_id),
+                    Some(user_message_id),
+                    ctx.model_version_id,
+                    "failed",
+                    Some(&e.to_string()),
+                )
+                .await?;
+
+                Err(AppError::AiError(e))
+            }
+        }
+    }
+}
diff --git a/lib/service/agent/session.rs b/lib/service/agent/session.rs
new file mode 100644
index 0000000..f1e15fb
--- /dev/null
+++ b/lib/service/agent/session.rs
@@ -0,0 +1,486 @@
+use chrono::Utc;
+use db::sqlx;
+use model::agent::AgentSessionModel;
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+#[derive(Debug, Clone, Deserialize, ToSchema)]
+pub struct CreateAgentSession {
+    pub name: String,
+    pub agent_kind: String,
+    pub model_version: Uuid,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub system_prompt: Option<String>,
+    #[serde(default)]
+    pub temperature: Option<f32>,
+    pub max_output_tokens: Option<i32>,
+    pub tool_policy: Option<String>,
+    pub toolset_json: Option<String>,
+    pub memory_provider: Option<String>,
+    pub memory_provider_config: Option<String>,
+    pub iteration_budget: Option<i32>,
+    pub source: Option<String>,
+    pub visibility: Option<String>,
+    pub wk: Option<String>,
+    pub knowledge_base_ids: Option<Vec<Uuid>>,
+    pub variables: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, ToSchema)]
+pub struct UpdateAgentSession {
+    pub name: Option<String>,
+    pub description: Option<String>,
+    pub system_prompt: Option<String>,
+    pub temperature: Option<f32>,
+    pub max_output_tokens: Option<i32>,
+    pub model_version: Option<Uuid>,
+    pub tool_policy: Option<String>,
+    pub toolset_json: Option<String>,
+    pub memory_provider: Option<String>,
+    pub memory_provider_config: Option<String>,
+    pub iteration_budget: Option<i32>,
+    pub visibility: Option<String>,
+    pub enabled: Option<bool>,
+    pub knowledge_base_ids: Option<Vec<Uuid>>,
+    pub variables: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, ToSchema)]
+pub struct AgentSessionResponse {
+    pub id: Uuid,
+    pub name: String,
+    pub description: Option<String>,
+    pub agent_kind: String,
+    pub model_version: Option<Uuid>,
+    pub system_prompt: Option<String>,
+    pub temperature: Option<f32>,
+    pub max_output_tokens: Option<i32>,
+    pub tool_policy: Option<String>,
+    pub toolset_json: Option<String>,
+    pub memory_provider: Option<String>,
+    pub iteration_budget: Option<i32>,
+    pub source: Option<String>,
+    pub parent_session_id: Option<Uuid>,
+    pub visibility: String,
+    pub version: i32,
+    pub enabled: bool,
+    pub user: Option<Uuid>,
+    pub wk: Option<Uuid>,
+    pub variables: Option<String>,
+    pub published_at: Option<chrono::DateTime<Utc>>,
+    pub created_at: chrono::DateTime<Utc>,
+    pub updated_at: chrono::DateTime<Utc>,
+}
+
+impl AppService {
+    pub async fn agent_session_create(
+        &self,
+        user_id: Uuid,
+        params: CreateAgentSession,
+    ) -> Result<AgentSessionResponse, AppError> {
+        let wk_uuid: Option<Uuid> = if let Some(ref wk_name) = params.wk {
+            let wk = crate::AppService::workspace_resolve(
+                &*self, wk_name,
+            )
+            .await?;
+            let _ = crate::AppService::workspace_require_member(
+                &*self, wk.id, user_id,
+            )
+            .await?;
+            Some(wk.id)
+        } else {
+            None
+        };
+
+        let id = Uuid::now_v7();
+        let now = Utc::now();
+        let visibility = params.visibility.unwrap_or_else(|| "private".to_string());
+        let kb_ids = params.knowledge_base_ids.map(|ids| {
+            ids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(",")
+        });
+
+        let row = sqlx::query_as::<_, AgentSessionModel>(
+            "INSERT INTO agent_session \
+             (id, \"user\", wk, name, description, agent_kind, model_version, \
+              system_prompt, temperature, max_output_tokens, tool_policy, \
+              knowledge_base_ids, variables, visibility, version, enabled, \
+              source, toolset_json, memory_provider, memory_provider_config, iteration_budget, \
+              created_by, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, 1, true, \
+                     'api', '{}', 'simple', '{}', 90, \
+                     $15, $16, $16) \
+             RETURNING id, \"user\", wk, name, description, agent_kind, model_version, \
+                       system_prompt, temperature, max_output_tokens, tool_policy, \
+                       knowledge_base_ids, variables, visibility, version, \
+                       published_at, rollback_from_version, enabled, \
+                       source, parent_session_id, toolset_json, \
+                       memory_provider, memory_provider_config, iteration_budget, \
+                       created_by, created_at, updated_at, deleted_at",
+        )
+        .bind(id)
+        .bind(user_id)
+        .bind(wk_uuid)
+        .bind(&params.name)
+        .bind(&params.description)
+        .bind(&params.agent_kind)
+        .bind(params.model_version)
+        .bind(&params.system_prompt)
+        .bind(params.temperature)
+        .bind(params.max_output_tokens)
+        .bind(&params.tool_policy)
+        .bind(&kb_ids)
+        .bind(&params.variables)
+        .bind(&visibility)
+        .bind(user_id)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.into())
+    }
+
+    pub async fn agent_session_list(
+        &self,
+        user_id: Uuid,
+    ) -> Result<Vec<AgentSessionResponse>, AppError> {
+        let rows = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, tool_policy, \
+             knowledge_base_ids, variables, visibility, version, \
+             published_at, rollback_from_version, enabled, \
+             source, parent_session_id, toolset_json, \
+             memory_provider, memory_provider_config, iteration_budget, \
+             created_by, created_at, updated_at, deleted_at \
+             FROM agent_session \
+             WHERE (\"user\" = $1 OR wk IN (SELECT wk FROM wk_member WHERE \"user\" = $1)) \
+               AND deleted_at IS NULL \
+             ORDER BY updated_at DESC",
+        )
+        .bind(user_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    pub async fn agent_session_get(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+    ) -> Result<AgentSessionResponse, AppError> {
+        let row = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, tool_policy, \
+             knowledge_base_ids, variables, visibility, version, \
+             published_at, rollback_from_version, enabled, source, parent_session_id, toolset_json, memory_provider, memory_provider_config, iteration_budget, created_by, \
+             created_at, updated_at, deleted_at \
+             FROM agent_session \
+             WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        if row.user != Some(user_id) {
+            if let Some(wk) = row.wk {
+                let _ = crate::AppService::workspace_require_member(
+                    &*self, wk, user_id,
+                )
+                .await?;
+            } else {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        Ok(row.into())
+    }
+
+    pub async fn agent_session_update(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+        params: UpdateAgentSession,
+    ) -> Result<AgentSessionResponse, AppError> {
+        let existing = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, tool_policy, \
+             knowledge_base_ids, variables, visibility, version, \
+             published_at, rollback_from_version, enabled, source, parent_session_id, toolset_json, memory_provider, memory_provider_config, iteration_budget, created_by, \
+             created_at, updated_at, deleted_at \
+             FROM agent_session \
+             WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        if existing.user != Some(user_id) {
+            if let Some(wk) = existing.wk {
+                let _ = crate::AppService::workspace_require_admin(
+                    &*self, wk, user_id,
+                )
+                .await?;
+            } else {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        let now = Utc::now();
+        let name = params.name.unwrap_or(existing.name);
+        let description = params.description.or(existing.description);
+        let system_prompt = params.system_prompt.or(existing.system_prompt);
+        let temperature = params.temperature.or(existing.temperature);
+        let max_output_tokens = params.max_output_tokens.or(existing.max_output_tokens);
+        let model_version = params.model_version.or(existing.model_version);
+        let tool_policy = params.tool_policy.or(existing.tool_policy);
+        let toolset_json = params.toolset_json.or(existing.toolset_json);
+        let memory_provider = params.memory_provider.or(existing.memory_provider);
+        let memory_provider_config = params.memory_provider_config.or(existing.memory_provider_config);
+        let iteration_budget = params.iteration_budget.or(existing.iteration_budget);
+        let visibility = params.visibility.unwrap_or(existing.visibility);
+        let enabled = params.enabled.unwrap_or(existing.enabled);
+        let kb_ids = params
+            .knowledge_base_ids
+            .map(|ids| ids.iter().map(|id| id.to_string()).collect::<Vec<_>>().join(","))
+            .or(existing.knowledge_base_ids);
+        let variables = params.variables.or(existing.variables);
+
+        let row = sqlx::query_as::<_, AgentSessionModel>(
+            "UPDATE agent_session SET \
+             name = $1, description = $2, system_prompt = $3, temperature = $4, \
+             max_output_tokens = $5, model_version = $6, tool_policy = $7, \
+             toolset_json = $8, memory_provider = $9, \
+             memory_provider_config = $10, iteration_budget = $11, \
+             visibility = $12, enabled = $13, knowledge_base_ids = $14, \
+             variables = $15, updated_at = $16 \
+             WHERE id = $17 AND deleted_at IS NULL \
+             RETURNING id, \"user\", wk, name, description, agent_kind, model_version, \
+                       system_prompt, temperature, max_output_tokens, tool_policy, \
+                       knowledge_base_ids, variables, visibility, version, \
+                       published_at, rollback_from_version, enabled, source, parent_session_id, toolset_json, memory_provider, memory_provider_config, iteration_budget, created_by, \
+                       created_at, updated_at, deleted_at",
+        )
+        .bind(&name)
+        .bind(&description)
+        .bind(&system_prompt)
+        .bind(temperature)
+        .bind(max_output_tokens)
+        .bind(model_version)
+        .bind(&tool_policy)
+        .bind(&toolset_json)
+        .bind(&memory_provider)
+        .bind(&memory_provider_config)
+        .bind(iteration_budget)
+        .bind(&visibility)
+        .bind(enabled)
+        .bind(&kb_ids)
+        .bind(&variables)
+        .bind(now)
+        .bind(session_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.into())
+    }
+
+    pub async fn agent_session_delete(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+    ) -> Result<(), AppError> {
+        let existing = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, tool_policy, \
+             knowledge_base_ids, variables, visibility, version, \
+             published_at, rollback_from_version, enabled, source, parent_session_id, toolset_json, memory_provider, memory_provider_config, iteration_budget, created_by, \
+             created_at, updated_at, deleted_at \
+             FROM agent_session \
+             WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        if existing.user != Some(user_id) {
+            if let Some(wk) = existing.wk {
+                let _ = crate::AppService::workspace_require_admin(
+                    &*self, wk, user_id,
+                )
+                .await?;
+            } else {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        let now = Utc::now();
+        sqlx::query(
+            "UPDATE agent_session SET deleted_at = $1, updated_at = $1 WHERE id = $2",
+        )
+        .bind(now)
+        .bind(session_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+    pub async fn agent_session_search(
+        &self,
+        user_id: Uuid,
+        query: &str,
+        limit: u32,
+    ) -> Result<Vec<AgentSessionResponse>, AppError> {
+        let rows = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT DISTINCT s.id, s.\"user\", s.wk, s.name, s.description, \
+                    s.agent_kind, s.model_version, \
+                    s.system_prompt, s.temperature, s.max_output_tokens, s.tool_policy, \
+                    s.knowledge_base_ids, s.variables, s.visibility, s.version, \
+                    s.published_at, s.rollback_from_version, s.enabled, \
+                    s.source, s.parent_session_id, s.toolset_json, \
+                    s.memory_provider, s.memory_provider_config, s.iteration_budget, \
+                    s.created_by, s.created_at, s.updated_at, s.deleted_at \
+             FROM agent_session s \
+             INNER JOIN agent_message m ON m.conversation IN ( \
+                SELECT id FROM agent_conversation WHERE session = s.id \
+             ) \
+             WHERE (s.\"user\" = $1 OR s.wk IN (SELECT wk FROM wk_member WHERE \"user\" = $1)) \
+               AND s.deleted_at IS NULL \
+               AND m.deleted_at IS NULL \
+               AND m.search_vector @@ plainto_tsquery('english', $2) \
+             ORDER BY s.updated_at DESC \
+             LIMIT $3",
+        )
+        .bind(user_id)
+        .bind(query)
+        .bind(limit as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+    pub async fn agent_session_update_toolsets(
+        &self,
+        user_id: Uuid,
+        session_id: Uuid,
+        enabled: Option<Vec<String>>,
+        disabled: Option<Vec<String>>,
+    ) -> Result<AgentSessionResponse, AppError> {
+        let existing = sqlx::query_as::<_, AgentSessionModel>(
+            "SELECT id, \"user\", wk, name, description, agent_kind, model_version, \
+             system_prompt, temperature, max_output_tokens, tool_policy, \
+             knowledge_base_ids, variables, visibility, version, \
+             published_at, rollback_from_version, enabled, source, parent_session_id, toolset_json, memory_provider, memory_provider_config, iteration_budget, created_by, \
+             created_at, updated_at, deleted_at \
+             FROM agent_session \
+             WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(session_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("agent session not found".to_string()))?;
+
+        if existing.user != Some(user_id) {
+            if let Some(wk) = existing.wk {
+                let _ = crate::AppService::workspace_require_admin(
+                    &*self, wk, user_id,
+                )
+                .await?;
+            } else {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        let toolset_json = {
+            let mut current: serde_json::Map<String, serde_json::Value> =
+                existing
+                    .toolset_json
+                    .as_deref()
+                    .and_then(|s| serde_json::from_str(s).ok())
+                    .unwrap_or_default();
+
+            if let Some(en) = enabled {
+                current.insert(
+                    "enabled".to_string(),
+                    serde_json::Value::Array(
+                        en.into_iter().map(serde_json::Value::String).collect(),
+                    ),
+                );
+            }
+            if let Some(dis) = disabled {
+                current.insert(
+                    "disabled".to_string(),
+                    serde_json::Value::Array(
+                        dis.into_iter().map(serde_json::Value::String).collect(),
+                    ),
+                );
+            }
+            Some(serde_json::to_string(&current).unwrap_or_default())
+        };
+
+        let now = Utc::now();
+        let row = sqlx::query_as::<_, AgentSessionModel>(
+            "UPDATE agent_session SET toolset_json = $1, updated_at = $2 \
+             WHERE id = $3 AND deleted_at IS NULL \
+             RETURNING id, \"user\", wk, name, description, agent_kind, model_version, \
+                       system_prompt, temperature, max_output_tokens, tool_policy, \
+                       knowledge_base_ids, variables, visibility, version, \
+                       published_at, rollback_from_version, enabled, source, parent_session_id, toolset_json, memory_provider, memory_provider_config, iteration_budget, created_by, \
+                       created_at, updated_at, deleted_at",
+        )
+        .bind(&toolset_json)
+        .bind(now)
+        .bind(session_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.into())
+    }
+}
+
+impl From<AgentSessionModel> for AgentSessionResponse {
+    fn from(m: AgentSessionModel) -> Self {
+        Self {
+            id: m.id,
+            name: m.name,
+            description: m.description,
+            agent_kind: m.agent_kind,
+            model_version: m.model_version,
+            system_prompt: m.system_prompt,
+            temperature: m.temperature,
+            max_output_tokens: m.max_output_tokens,
+            tool_policy: m.tool_policy,
+            toolset_json: m.toolset_json,
+            memory_provider: m.memory_provider,
+            iteration_budget: m.iteration_budget,
+            source: m.source,
+            parent_session_id: m.parent_session_id,
+            visibility: m.visibility,
+            version: m.version,
+            enabled: m.enabled,
+            user: m.user,
+            wk: m.wk,
+            variables: m.variables,
+            published_at: m.published_at,
+            created_at: m.created_at,
+            updated_at: m.updated_at,
+        }
+    }
+}
diff --git a/lib/service/agent/sse.rs b/lib/service/agent/sse.rs
new file mode 100644
index 0000000..e3d081b
--- /dev/null
+++ b/lib/service/agent/sse.rs
@@ -0,0 +1,378 @@
+use std::sync::Arc;
+
+use ai::agent::{RigAgent, RigStreamChunk, RigToolSet};
+use ai::tool::register::ToolRegister;
+use serde_json::{json, Value};
+use tokio::sync::mpsc;
+use tracing::{error, info, warn};
+use uuid::Uuid;
+
+use super::run::AppAgentContext;
+use super::types::AgentRunRequest;
+use crate::error::AppError;
+use crate::AppService;
+
+impl AppService {
+    pub async fn agent_run_streaming(
+        &self,
+        user_id: Uuid,
+        req: AgentRunRequest,
+    ) -> Result<mpsc::UnboundedReceiver<String>, AppError> {
+        let ctx = self.agent_session_context(req.session_id, user_id).await?;
+        let conversation_id = req
+            .conversation_id
+            .ok_or_else(|| AppError::BadRequest("conversation_id is required".to_string()))?;
+        let conversation = self
+            .agent_require_conversation_access(user_id, conversation_id)
+            .await?;
+        if conversation.session != ctx.session_id {
+            return Err(AppError::BadRequest(
+                "conversation does not belong to session".to_string(),
+            ));
+        }
+
+        let ai_client = self.agent_build_ai_client(ctx.model_version_id).await?;
+        let agent_config = self.agent_build_config(&ctx, req.max_steps);
+
+        self.agent_maybe_compact(&ai_client, &ctx.provider_model_name, conversation_id)
+            .await
+            .unwrap_or_else(|e| {
+                warn!(error = %e, "compaction check failed, continuing");
+            });
+
+        let mut tools: ToolRegister<AppAgentContext> = ToolRegister::new();
+        if conversation.title == "New Chat" || conversation.title.trim().is_empty() {
+            tools.register(super::tools::SetTitleTool::new());
+        }
+        tools.register(super::memory::SaveMemoryTool::new());
+        let (memories_text, _memory_rows) =
+            self.agent_load_memories(ctx.session_id).await?;
+        if !memories_text.is_empty() {
+            tools.register(super::memory::RecallMemoryTool::new(memories_text));
+        }
+
+        // Git RPC tools
+        super::git_tools::register_git_tools(&mut tools);
+        super::workspace_tools::register_workspace_tools(&mut tools);
+        super::issue_tools::register_issue_tools(&mut tools);
+
+        let (tx, rx) = mpsc::unbounded_channel::<String>();
+
+        let agent = RigAgent::new(ai_client.clone(), agent_config)
+            .map_err(|e| AppError::AiError(e))?;
+
+        let timeout_secs = req.timeout_secs.unwrap_or(300);
+
+        let agent_request = self
+            .agent_build_request(
+                &ai_client,
+                &ctx,
+                req.conversation_id,
+                req.input.clone(),
+                Some(timeout_secs),
+            )
+            .await?;
+
+        let invocation_id = Uuid::now_v7();
+        let ctx_clone = ctx.clone();
+        let self_clone = self.clone();
+
+        info!(
+            invocation_id = %invocation_id,
+            session_id = %ctx.session_id,
+            user_id = %user_id,
+            "agent sse stream starting"
+        );
+
+        if let Err(e) = self.cache.set::<Uuid>(
+            &format!("agent:stream:active:{}", conversation_id),
+            &invocation_id,
+        ).await {
+            warn!(error = %e, "agent sse: failed to mark stream active");
+        }
+
+        let user_message_id = match self
+            .persist_user_message(conversation_id, user_id, &req.input)
+            .await
+        {
+            Ok(id) => Some(id),
+            Err(e) => {
+                let _ = tx.send(super::persistence::stream_error("failed to persist user message"));
+                let _ = self.cache
+                    .remove(&format!("agent:stream:active:{}", conversation_id))
+                    .await;
+                return Err(e);
+            }
+        };
+
+        let first_input = req.input.clone();
+
+        let shared_ctx = Arc::new(tokio::sync::Mutex::new(AppAgentContext {
+            user_id,
+            session_id: ctx.session_id,
+            conversation_id,
+            pending_title: None,
+            pending_memories: Vec::new(),
+            git: Some(super::run::GitAgentContext {
+                channel: self.git.clone(),
+                db: self.db.clone(),
+                cache: self.cache.clone(),
+            }),
+        }));
+
+        let mut tool_set = RigToolSet::from_register(&tools, shared_ctx);
+        let rig_tools = tool_set.take_tools();
+        let (mut chunk_rx, handle) = agent.run(agent_request, rig_tools);
+
+        let trace_svc = self.clone();
+
+        tokio::spawn(async move {
+            let mut tracer = super::trace::TraceAccumulator::new(
+                trace_svc, invocation_id, conversation_id,
+            );
+            let mut phase: &str = "think";
+            while let Some(chunk) = chunk_rx.recv().await {
+                let (new_phase, sse_event) = process_chunk_with_phase(&chunk, phase, &mut tracer).await;
+                if new_phase != phase {
+                    phase = new_phase;
+                    let _ = tx.send(phase_sse(phase));
+                }
+                if let Some(sse) = sse_event {
+                    let _ = tx.send(sse);
+                }
+            }
+            let agent_result = match tokio::time::timeout(
+                std::time::Duration::from_secs(timeout_secs),
+                handle,
+            )
+            .await
+            {
+                Ok(Ok(inner)) => inner,
+                Ok(Err(e)) => Err(ai::error::AiError::Response(e.to_string())),
+                Err(_) => Err(ai::error::AiError::Timeout { seconds: timeout_secs }),
+            };
+
+            let _ = self_clone.cache
+                .remove(&format!("agent:stream:active:{}", conversation_id))
+                .await;
+
+            let agent_ctx = tool_set.into_context();
+
+            match agent_result {
+                Ok(result) => {
+                    let reasoning_content: Option<String> = {
+                        let collected: Vec<String> = result
+                            .steps
+                            .iter()
+                            .filter_map(|step| step.reasoning_content.clone())
+                            .collect();
+                        if collected.is_empty() { None } else { Some(collected.join("\n\n")) }
+                    };
+
+                    match self_clone
+                        .persist_assistant_message(
+                            conversation_id,
+                            ctx_clone.session_id,
+                            &result.output,
+                            reasoning_content.as_deref(),
+                            invocation_id,
+                        )
+                        .await
+                    {
+                        Ok(msg_id) => {
+                            for step in &result.steps {
+                                for tc in &step.tool_calls {
+                                    let _ = self_clone
+                                        .agent_record_tool_call(
+                                            invocation_id, ctx_clone.session_id,
+                                            Some(conversation_id), Some(msg_id),
+                                            &tc.id, &tc.name,
+                                            Some(&tc.arguments.to_string()),
+                                            tc.output.as_ref().map(|v| v.to_string()).as_deref(),
+                                            tc.error.as_deref(),
+                                            if tc.error.is_some() { "error" } else { "success" },
+                                            tc.elapsed_ms,
+                                        )
+                                        .await;
+                                }
+                            }
+
+                            let _ = self_clone.persist_billing_and_deduct(
+                                &ctx_clone, invocation_id,
+                                result.input_tokens, result.output_tokens,
+                            ).await;
+
+                            let _ = self_clone.agent_record_invocation(
+                                invocation_id, ctx_clone.session_id,
+                                Some(conversation_id), Some(msg_id),
+                                ctx_clone.model_version_id, "completed", None,
+                            ).await;
+
+                            let _ = self_clone.update_conversation_timestamp(conversation_id).await;
+
+                            let title = agent_ctx.pending_title
+                                .filter(|t| !t.trim().is_empty())
+                                .or_else(|| {
+                                    let first_line = first_input.lines().next().unwrap_or(&first_input);
+                                    let truncated: String = first_line.chars().take(50).collect();
+                                    if truncated.trim().is_empty() { None }
+                                    else { Some(if first_line.len() > 50 { format!("{}…", truncated.trim_end()) } else { truncated.trim().to_string() }) }
+                                });
+                            if let Some(new_title) = &title {
+                                if self_clone.update_conversation_title(conversation_id, new_title).await.is_ok() {
+                                    let title_event = serde_json::json!({
+                                        "type": "title_updated",
+                                        "conversation_id": conversation_id.to_string(),
+                                        "title": new_title,
+                                    });
+                                    let _ = tx.send(format!("data: {}\n\n", title_event));
+                                }
+                            }
+
+                            if !agent_ctx.pending_memories.is_empty() {
+                                let _ = self_clone.agent_persist_memories(
+                                    ctx_clone.session_id, &agent_ctx.pending_memories,
+                                ).await;
+                            }
+
+                            let _ = tx.send(done_sse_with_phase(msg_id, &result.output, "summarize"));
+                            info!(invocation_id = %invocation_id, message_id = %msg_id, "agent sse stream completed");
+                        }
+                        Err(e) => {
+                            error!(error = %e, "sse: failed to persist assistant message");
+                            let _ = tx.send(super::persistence::stream_error("persistence failed"));
+                        }
+                    }
+                }
+                Err(e) => {
+                    warn!(invocation_id = %invocation_id, error = %e, "agent sse stream failed");
+                    let _ = tx.send(super::persistence::stream_error(&e.to_string()));
+                    let error_content = format!(
+                        "I encountered an error while processing your request: {}", e
+                    );
+                    let _ = self_clone.persist_assistant_message(
+                        conversation_id, ctx_clone.session_id, &error_content, None, invocation_id,
+                    ).await;
+                    let _ = self_clone.agent_record_invocation(
+                        invocation_id, ctx_clone.session_id,
+                        Some(conversation_id), user_message_id,
+                        ctx_clone.model_version_id, "failed", Some(&e.to_string()),
+                    ).await;
+                }
+            }
+        });
+
+        Ok(rx)
+    }
+}
+async fn process_chunk_with_phase(
+    chunk: &RigStreamChunk,
+    _current_phase: &str,
+    tracer: &mut super::trace::TraceAccumulator,
+) -> (&'static str, Option<String>) {
+    match chunk {
+        RigStreamChunk::Thinking { content, .. } => {
+            tracer.feed_thinking(content).await;
+            ("think", Some(format_chunk_sse(chunk)))
+        }
+        RigStreamChunk::TextDelta { content, .. } => {
+            tracer.feed_text(content).await;
+            ("answer", Some(format_chunk_sse(chunk)))
+        }
+        RigStreamChunk::ToolCallStarted { tool_call_id, tool_name, arguments } => {
+            let args_val: Value = serde_json::from_str(arguments).unwrap_or(Value::Null);
+            tracer.feed_tool_call(tool_call_id, tool_name, &args_val).await;
+            ("act", Some(format_chunk_sse(chunk)))
+        }
+        RigStreamChunk::ToolCallFinished { tool_call_id, tool_name, output, error } => {
+            let out_val: Option<Value> = match output {
+                o if o.is_empty() => None,
+                o => serde_json::from_str(o).ok(),
+            };
+            tracer.feed_tool_result(tool_call_id, tool_name, out_val.as_ref(), error.as_deref(), 0).await;
+            ("act", Some(format_chunk_sse(chunk)))
+        }
+        RigStreamChunk::Final { content, input_tokens, output_tokens } => {
+            tracer.finish(content, *input_tokens as i64, *output_tokens as i64).await;
+            ("summarize", Some(format_chunk_sse(chunk)))
+        }
+        RigStreamChunk::Failed { .. } => ("summarize", None),
+        RigStreamChunk::SubagentStarted { .. } => ("act", Some(format_chunk_sse(chunk))),
+        RigStreamChunk::SubagentCompleted { .. } => ("act", Some(format_chunk_sse(chunk))),
+        RigStreamChunk::SubagentFailed { .. } => ("summarize", Some(format_chunk_sse(chunk))),
+    }
+}
+
+fn format_chunk_sse(chunk: &RigStreamChunk) -> String {
+    let payload = match chunk {
+        RigStreamChunk::TextDelta { index, content } => json!({
+            "type": "delta", "index": index, "content": content,
+        }),
+        RigStreamChunk::Thinking { index, content } => json!({
+            "type": "thinking", "index": index, "content": content,
+        }),
+        RigStreamChunk::ToolCallStarted { tool_call_id, tool_name, arguments } => json!({
+            "type": "tool_call_started",
+            "tool_call_id": tool_call_id,
+            "tool_name": tool_name,
+            "arguments": arguments,
+        }),
+        RigStreamChunk::ToolCallFinished { tool_call_id, tool_name, output, error } => json!({
+            "type": "tool_call_finished",
+            "tool_call_id": tool_call_id,
+            "tool_name": tool_name,
+            "output": output,
+            "error": error,
+        }),
+        RigStreamChunk::SubagentStarted { subagent_id, role, task } => json!({
+            "type": "subagent_started",
+            "subagent_id": subagent_id,
+            "role": role,
+            "task": task,
+        }),
+        RigStreamChunk::SubagentCompleted { subagent_id, role, task, output } => json!({
+            "type": "subagent_completed",
+            "subagent_id": subagent_id,
+            "role": role,
+            "task": task,
+            "output": output,
+        }),
+        RigStreamChunk::SubagentFailed { error } => json!({
+            "type": "subagent_failed",
+            "error": error,
+        }),
+        RigStreamChunk::Final { .. } | RigStreamChunk::Failed { .. } => return String::new(),
+    };
+    format!("data: {}\n\n", payload)
+}
+
+fn phase_sse(phase: &str) -> String {
+    let payload = json!({
+        "type": "phase_change",
+        "phase": phase,
+        "label": phase_label(phase),
+    });
+    format!("data: {}\n\n", payload)
+}
+
+fn phase_label(phase: &str) -> &str {
+    match phase {
+        "think" => "Thinking",
+        "answer" => "Answering",
+        "act" => "Acting",
+        "summarize" => "Summarizing",
+        _ => phase,
+    }
+}
+
+fn done_sse_with_phase(message_id: Uuid, output: &str, phase: &str) -> String {
+    let payload = json!({
+        "type": "done",
+        "message_id": message_id.to_string(),
+        "status": "completed",
+        "phase": phase,
+        "label": phase_label(phase),
+        "output": output,
+    });
+    format!("data: {}\n\n", payload)
+}
diff --git a/lib/service/agent/tools.rs b/lib/service/agent/tools.rs
new file mode 100644
index 0000000..6aa4668
--- /dev/null
+++ b/lib/service/agent/tools.rs
@@ -0,0 +1,70 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use serde_json::{json, Value};
+
+use super::run::AppAgentContext;
+pub struct SetTitleTool;
+
+impl SetTitleTool {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Default for SetTitleTool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl FunctionCall for SetTitleTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str {
+        "set_conversation_title"
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": "string",
+                    "description": "A concise, descriptive title for the conversation (max 100 characters)"
+                }
+            },
+            "required": ["title"]
+        })
+    }
+
+    async fn call(
+        &self,
+        context: &mut Self::Context,
+        args: Value,
+    ) -> AiResult<Value> {
+        let title = args
+            .get("title")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| AiError::Config("title parameter is required".to_string()))?;
+
+        let title = title.trim();
+        if title.is_empty() {
+            return Err(AiError::Config("title cannot be empty".to_string()));
+        }
+
+        let title = if title.len() > 100 {
+            &title[..100]
+        } else {
+            title
+        };
+
+        context.pending_title = Some(title.to_string());
+
+        Ok(json!({
+            "success": true,
+            "title": title
+        }))
+    }
+}
diff --git a/lib/service/agent/trace.rs b/lib/service/agent/trace.rs
new file mode 100644
index 0000000..975acd1
--- /dev/null
+++ b/lib/service/agent/trace.rs
@@ -0,0 +1,268 @@
+use chrono::Utc;
+use db::sqlx;
+use model::agent::AgentTraceModel;
+use serde_json::{json, Value};
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+pub struct TraceContext {
+    pub invocation_id: Uuid,
+    pub conversation_id: Uuid,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct TraceReplay {
+    pub invocation_id: Uuid,
+    pub conversation_id: Uuid,
+    pub phases: Vec<TracePhaseRow>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct TracePhaseRow {
+    pub id: Uuid,
+    pub sequence: i32,
+    pub phase: String,
+    pub label: String,
+    pub content: Option<String>,
+    pub tool_calls: Option<Value>,
+    pub tool_results: Option<Value>,
+    pub input_tokens: Option<i64>,
+    pub output_tokens: Option<i64>,
+    pub metadata: Option<Value>,
+    pub created_at: chrono::DateTime<Utc>,
+}
+
+impl AppService {
+    pub async fn trace_record(
+        &self,
+        ctx: &TraceContext,
+        sequence: i32,
+        phase: &str,
+        content: Option<&str>,
+        tool_calls: Option<&Value>,
+        tool_results: Option<&Value>,
+        input_tokens: Option<i64>,
+        output_tokens: Option<i64>,
+        metadata: Option<&Value>,
+    ) -> Result<Uuid, AppError> {
+        let id = Uuid::now_v7();
+        let now = Utc::now();
+        sqlx::query(
+            "INSERT INTO agent_trace \
+             (id, invocation, conversation, sequence, phase, content, \
+              tool_calls, tool_results, input_tokens, output_tokens, metadata, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)",
+        )
+        .bind(id)
+        .bind(ctx.invocation_id)
+        .bind(ctx.conversation_id)
+        .bind(sequence)
+        .bind(phase)
+        .bind(content)
+        .bind(tool_calls)
+        .bind(tool_results)
+        .bind(input_tokens)
+        .bind(output_tokens)
+        .bind(metadata)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(id)
+    }
+
+    pub async fn trace_replay_by_invocation(
+        &self,
+        invocation_id: Uuid,
+    ) -> Result<TraceReplay, AppError> {
+        let rows = sqlx::query_as::<_, AgentTraceModel>(
+            "SELECT id, invocation, conversation, sequence, phase, content, \
+             tool_calls, tool_results, input_tokens, output_tokens, metadata, created_at \
+             FROM agent_trace WHERE invocation = $1 ORDER BY sequence ASC",
+        )
+        .bind(invocation_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let conversation_id = rows.first().map(|r| r.conversation).unwrap_or(Uuid::nil());
+
+        Ok(TraceReplay {
+            invocation_id,
+            conversation_id,
+            phases: rows
+                .into_iter()
+                .map(|r| TracePhaseRow {
+                    id: r.id,
+                    sequence: r.sequence,
+                    phase: r.phase.clone(),
+                    label: r.phase_label().to_string(),
+                    content: r.content,
+                    tool_calls: r.tool_calls,
+                    tool_results: r.tool_results,
+                    input_tokens: r.input_tokens,
+                    output_tokens: r.output_tokens,
+                    metadata: r.metadata,
+                    created_at: r.created_at,
+                })
+                .collect(),
+        })
+    }
+
+    pub async fn trace_replay_by_conversation(
+        &self,
+        conversation_id: Uuid,
+    ) -> Result<Vec<TraceReplay>, AppError> {
+        let rows = sqlx::query_as::<_, AgentTraceModel>(
+            "SELECT id, invocation, conversation, sequence, phase, content, \
+             tool_calls, tool_results, input_tokens, output_tokens, metadata, created_at \
+             FROM agent_trace WHERE conversation = $1 ORDER BY invocation, sequence ASC",
+        )
+        .bind(conversation_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut grouped: std::collections::BTreeMap<Uuid, Vec<AgentTraceModel>> =
+            std::collections::BTreeMap::new();
+        for row in rows {
+            grouped.entry(row.invocation).or_default().push(row);
+        }
+
+        Ok(grouped
+            .into_iter()
+            .map(|(invocation_id, rows)| TraceReplay {
+                invocation_id,
+                conversation_id,
+                phases: rows
+                    .into_iter()
+                    .map(|r| TracePhaseRow {
+                        id: r.id,
+                        sequence: r.sequence,
+                        phase: r.phase.clone(),
+                        label: r.phase_label().to_string(),
+                        content: r.content,
+                        tool_calls: r.tool_calls,
+                        tool_results: r.tool_results,
+                        input_tokens: r.input_tokens,
+                        output_tokens: r.output_tokens,
+                        metadata: r.metadata,
+                        created_at: r.created_at,
+                    })
+                    .collect(),
+            })
+            .collect())
+    }
+}
+
+pub struct TraceAccumulator {
+    ctx: TraceContext,
+    seq: i32,
+    think_buf: String,
+    answer_buf: String,
+    think_tokens: i64,
+    answer_tokens: i64,
+    svc: AppService,
+}
+
+impl TraceAccumulator {
+    pub fn new(svc: AppService, invocation_id: Uuid, conversation_id: Uuid) -> Self {
+        Self {
+            ctx: TraceContext { invocation_id, conversation_id },
+            seq: 0,
+            think_buf: String::new(),
+            answer_buf: String::new(),
+            think_tokens: 0,
+            answer_tokens: 0,
+            svc,
+        }
+    }
+
+    pub async fn feed_thinking(&mut self, chunk: &str) {
+        self.think_buf.push_str(chunk);
+        self.think_tokens += (chunk.chars().count() as f64 / 2.5).ceil() as i64;
+    }
+
+    pub async fn feed_text(&mut self, chunk: &str) {
+        if !self.think_buf.is_empty() {
+            self.flush_think().await;
+        }
+        self.answer_buf.push_str(chunk);
+        self.answer_tokens += (chunk.chars().count() as f64 / 2.5).ceil() as i64;
+    }
+
+    pub async fn feed_tool_call(&mut self, tool_call_id: &str, tool_name: &str, args: &Value) {
+        if !self.answer_buf.is_empty() {
+            self.flush_answer().await;
+        }
+        let _ = self.svc.trace_record(
+            &self.ctx, self.seq, "act",
+            None,
+            Some(&json!({ "tool_call_id": tool_call_id, "name": tool_name, "arguments": args })),
+            None,
+            None, None, None,
+        ).await;
+        self.seq += 1;
+    }
+
+    pub async fn feed_tool_result(&mut self, tool_call_id: &str, tool_name: &str,
+                                   output: Option<&Value>, error: Option<&str>, elapsed_ms: i64) {
+        let _ = self.svc.trace_record(
+            &self.ctx, self.seq, "act",
+            None,
+            None,
+            Some(&json!({
+                "tool_call_id": tool_call_id,
+                "name": tool_name,
+                "output": output,
+                "error": error,
+                "elapsed_ms": elapsed_ms,
+            })),
+            None, None, None,
+        ).await;
+        self.seq += 1;
+    }
+
+    pub async fn finish(&mut self, output: &str, input_tokens: i64, output_tokens: i64) {
+        if !self.think_buf.is_empty() {
+            self.flush_think().await;
+        }
+        if !self.answer_buf.is_empty() {
+            self.flush_answer().await;
+        }
+        let _ = self.svc.trace_record(
+            &self.ctx, self.seq, "summarize",
+            Some(output),
+            None, None,
+            Some(input_tokens), Some(output_tokens),
+            None,
+        ).await;
+    }
+
+    async fn flush_think(&mut self) {
+        let content = std::mem::take(&mut self.think_buf);
+        let tokens = self.think_tokens;
+        self.think_tokens = 0;
+        let _ = self.svc.trace_record(
+            &self.ctx, self.seq, "think",
+            Some(&content), None, None,
+            Some(tokens), None, None,
+        ).await;
+        self.seq += 1;
+    }
+
+    async fn flush_answer(&mut self) {
+        let content = std::mem::take(&mut self.answer_buf);
+        let tokens = self.answer_tokens;
+        self.answer_tokens = 0;
+        let _ = self.svc.trace_record(
+            &self.ctx, self.seq, "answer",
+            Some(&content), None, None,
+            None, Some(tokens), None,
+        ).await;
+        self.seq += 1;
+    }
+}
diff --git a/lib/service/agent/types.rs b/lib/service/agent/types.rs
new file mode 100644
index 0000000..ff29692
--- /dev/null
+++ b/lib/service/agent/types.rs
@@ -0,0 +1,102 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use utoipa::ToSchema;
+use uuid::Uuid;
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum BillingTarget {
+    User,
+    Workspace,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct AgentRunRequest {
+    pub session_id: Uuid,
+    pub conversation_id: Option<Uuid>,
+    pub input: String,
+    #[serde(default)]
+    pub stream: bool,
+    pub max_steps: Option<usize>,
+    pub timeout_secs: Option<u64>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct AgentRunResponse {
+    pub message_id: Uuid,
+    pub conversation_id: Uuid,
+    pub output: String,
+    pub steps: Vec<AgentStepInfo>,
+    pub usage: AgentUsageInfo,
+    pub cost: Option<AgentCostInfo>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct AgentStepInfo {
+    pub index: usize,
+    pub assistant: Option<String>,
+    pub tool_calls: Vec<AgentToolCallInfo>,
+    pub reflection: Option<String>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct AgentToolCallInfo {
+    pub id: String,
+    pub name: String,
+    pub arguments: Value,
+    pub output: Option<Value>,
+    pub error: Option<String>,
+    pub elapsed_ms: Option<i64>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct AgentUsageInfo {
+    pub input_tokens: i64,
+    pub output_tokens: i64,
+    pub total_tokens: i64,
+}
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct AgentCostInfo {
+    pub amount: String,
+    pub currency: String,
+}
+#[derive(Debug, Clone)]
+pub(crate) struct SessionContext {
+    pub session_id: Uuid,
+    pub user_id: Option<Uuid>,
+    pub workspace_id: Option<Uuid>,
+    pub system_prompt: String,
+    pub model_version_id: Uuid,
+    pub provider_model_name: String,
+    pub temperature: Option<f32>,
+    pub max_output_tokens: Option<i32>,
+    pub tool_policy_json: Option<String>,
+    pub toolset_json: Option<String>,
+    pub variables_json: Option<String>,
+    pub iteration_budget: Option<i32>,
+    pub memory_provider: Option<String>,
+    #[allow(dead_code)]
+    pub source: Option<String>,
+    #[allow(dead_code)]
+    pub parent_session_id: Option<Uuid>,
+    pub billing_target: BillingTarget,
+}
+#[derive(Debug, Clone)]
+pub(crate) struct BillingRecord {
+    pub invocation_id: Uuid,
+    pub session_id: Uuid,
+    pub model_version_id: Uuid,
+    pub input_tokens: i64,
+    pub output_tokens: i64,
+    pub cached_input_tokens: i64,
+    pub cache_read_tokens: i64,
+    pub cache_write_tokens: i64,
+    pub reasoning_tokens: i64,
+    pub total_tokens: i64,
+    pub cost: Option<rust_decimal::Decimal>,
+    pub currency: Option<String>,
+    pub created_at: DateTime<Utc>,
+}
+#[derive(Debug, Clone)]
+#[allow(dead_code)]
+pub(crate) struct RunPersistState {
+    pub message_id: Uuid,
+    pub conversation_id: Uuid,
+    pub invocation_id: Uuid,
+    pub billing: BillingRecord,
+}
diff --git a/lib/service/agent/workspace_tools/helpers.rs b/lib/service/agent/workspace_tools/helpers.rs
new file mode 100644
index 0000000..16a5691
--- /dev/null
+++ b/lib/service/agent/workspace_tools/helpers.rs
@@ -0,0 +1,59 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::register::ToolRegister;
+use db::sqlx;
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::agent::run::{AppAgentContext, GitAgentContext};
+
+pub fn register_workspace_tools(tools: &mut ToolRegister<AppAgentContext>) {
+    tools.register(super::workspace::WorkspaceInfoTool::new());
+    tools.register(super::workspace::WorkspaceMembersTool::new());
+    tools.register(super::workspace::WorkspaceGroupsTool::new());
+    tools.register(super::workspace::WorkspaceGroupMembersTool::new());
+}
+
+pub(super) async fn require_workspace_member(
+    git: &GitAgentContext,
+    user_id: Uuid,
+    workspace_name: &str,
+) -> AiResult<Uuid> {
+    let wk_id: Uuid = sqlx::query_scalar(
+        "SELECT id FROM workspace WHERE name = $1",
+    )
+    .bind(workspace_name)
+    .fetch_optional(git.db.reader())
+    .await
+    .map_err(AiError::Database)?
+    .ok_or_else(|| AiError::Config(format!("workspace '{workspace_name}' not found")))?;
+
+    let is_member: i64 = sqlx::query_scalar(
+        "SELECT COUNT(*) FROM wk_member \
+         WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+    )
+    .bind(wk_id)
+    .bind(user_id)
+    .fetch_one(git.db.reader())
+    .await
+    .map_err(AiError::Database)?;
+
+    if is_member == 0 {
+        return Err(AiError::Config(format!(
+            "user is not a member of workspace '{workspace_name}'"
+        )));
+    }
+
+    Ok(wk_id)
+}
+
+pub(super) fn git_ctx(ctx: &AppAgentContext) -> AiResult<&GitAgentContext> {
+    ctx.git
+        .as_ref()
+        .ok_or_else(|| AiError::Config("workspace tools are not available in this session".to_string()))
+}
+
+pub(super) fn arg_str<'a>(args: &'a Value, key: &str) -> AiResult<&'a str> {
+    args.get(key)
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| AiError::Config(format!("'{key}' parameter is required")))
+}
diff --git a/lib/service/agent/workspace_tools/mod.rs b/lib/service/agent/workspace_tools/mod.rs
new file mode 100644
index 0000000..bfc187a
--- /dev/null
+++ b/lib/service/agent/workspace_tools/mod.rs
@@ -0,0 +1,4 @@
+pub mod helpers;
+pub mod workspace;
+
+pub use helpers::register_workspace_tools;
diff --git a/lib/service/agent/workspace_tools/workspace.rs b/lib/service/agent/workspace_tools/workspace.rs
new file mode 100644
index 0000000..9cd5ac6
--- /dev/null
+++ b/lib/service/agent/workspace_tools/workspace.rs
@@ -0,0 +1,278 @@
+use ai::error::{AiError, AiResult};
+use ai::tool::tools::FunctionCall;
+use async_trait::async_trait;
+use db::sqlx;
+use serde_json::{json, Value};
+use uuid::Uuid;
+
+use super::helpers::{arg_str, git_ctx, require_workspace_member};
+use crate::agent::run::AppAgentContext;
+
+pub struct WorkspaceInfoTool;
+
+impl WorkspaceInfoTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for WorkspaceInfoTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for WorkspaceInfoTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "workspace_info" }
+
+    fn description(&self) -> &'static str {
+        "Get information about a workspace: name, description, avatar."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" }
+            },
+            "required": ["workspace"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let _wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+
+        let row = sqlx::query_as::<_, (String, String, String, chrono::DateTime<chrono::Utc>)>(
+            "SELECT name, description, avatar_url, created_at FROM workspace WHERE name = $1",
+        )
+        .bind(workspace)
+        .fetch_optional(git.db.reader())
+        .await
+        .map_err(AiError::Database)?
+        .ok_or_else(|| AiError::Config(format!("workspace '{workspace}' not found")))?;
+
+        let member_count: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM wk_member WHERE wk = (SELECT id FROM workspace WHERE name = $1) AND leave_at IS NULL",
+        )
+        .bind(workspace)
+        .fetch_one(git.db.reader())
+        .await
+        .map_err(AiError::Database)?;
+
+        Ok(json!({
+            "name": row.0,
+            "description": row.1,
+            "avatar_url": row.2,
+            "created_at": row.3.to_rfc3339(),
+            "member_count": member_count,
+        }))
+    }
+}
+
+pub struct WorkspaceMembersTool;
+
+impl WorkspaceMembersTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for WorkspaceMembersTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for WorkspaceMembersTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "workspace_members" }
+
+    fn description(&self) -> &'static str {
+        "List all members of a workspace with their roles."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "limit": { "type": "integer", "description": "Max results (default 50)" }
+            },
+            "required": ["workspace"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+        let limit = args.get("limit").and_then(|v| v.as_i64()).unwrap_or(50).min(200);
+
+        #[derive(sqlx::FromRow)]
+        struct MemberRow {
+            username: String,
+            display_name: Option<String>,
+            owner: bool,
+            admin: bool,
+        }
+
+        let rows: Vec<MemberRow> = sqlx::query_as(
+            "SELECT u.username, u.display_name, m.owner, m.admin \
+             FROM wk_member m \
+             INNER JOIN \"user\" u ON u.id = m.\"user\" \
+             WHERE m.wk = $1 AND m.leave_at IS NULL \
+             ORDER BY m.owner DESC, m.admin DESC \
+             LIMIT $2",
+        )
+        .bind(wk_id)
+        .bind(limit)
+        .fetch_all(git.db.reader())
+        .await
+        .map_err(AiError::Database)?;
+
+        let members: Vec<Value> = rows.iter().map(|r| json!({
+            "username": r.username,
+            "display_name": r.display_name,
+            "role": if r.owner { "owner" } else if r.admin { "admin" } else { "member" },
+        })).collect();
+
+        Ok(json!({ "members": members, "count": members.len() }))
+    }
+}
+
+pub struct WorkspaceGroupsTool;
+
+impl WorkspaceGroupsTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for WorkspaceGroupsTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for WorkspaceGroupsTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "workspace_groups" }
+
+    fn description(&self) -> &'static str {
+        "List all user groups in a workspace."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" }
+            },
+            "required": ["workspace"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+
+        #[derive(sqlx::FromRow)]
+        struct GroupRow {
+            id: Uuid,
+            name: String,
+            created_at: chrono::DateTime<chrono::Utc>,
+        }
+
+        let rows: Vec<GroupRow> = sqlx::query_as(
+            "SELECT id, name, created_at FROM wk_group \
+             WHERE wk = $1 AND is_deleted = FALSE ORDER BY name ASC",
+        )
+        .bind(wk_id)
+        .fetch_all(git.db.reader())
+        .await
+        .map_err(AiError::Database)?;
+
+        // For each group, count members
+        let mut groups: Vec<Value> = Vec::new();
+        for row in &rows {
+            let count: i64 = sqlx::query_scalar(
+                "SELECT COUNT(*) FROM wk_gp_member WHERE gp = $1",
+            )
+            .bind(row.id)
+            .fetch_one(git.db.reader())
+            .await
+            .map_err(AiError::Database)?;
+
+            groups.push(json!({
+                "name": row.name,
+                "member_count": count,
+                "created_at": row.created_at.to_rfc3339(),
+            }));
+        }
+
+        Ok(json!({ "groups": groups, "count": groups.len() }))
+    }
+}
+
+pub struct WorkspaceGroupMembersTool;
+
+impl WorkspaceGroupMembersTool {
+    pub fn new() -> Self { Self }
+}
+
+impl Default for WorkspaceGroupMembersTool {
+    fn default() -> Self { Self::new() }
+}
+
+#[async_trait]
+impl FunctionCall for WorkspaceGroupMembersTool {
+    type Context = AppAgentContext;
+
+    fn name(&self) -> &'static str { "workspace_group_members" }
+
+    fn description(&self) -> &'static str {
+        "List members of a specific workspace group."
+    }
+
+    fn schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "workspace": { "type": "string", "description": "Workspace name" },
+                "group_name": { "type": "string", "description": "Group name" }
+            },
+            "required": ["workspace", "group_name"]
+        })
+    }
+
+    async fn call(&self, ctx: &mut AppAgentContext, args: Value) -> AiResult<Value> {
+        let git = git_ctx(ctx)?;
+        let workspace = arg_str(&args, "workspace")?;
+        let group_name = arg_str(&args, "group_name")?;
+        let wk_id = require_workspace_member(git, ctx.user_id, workspace).await?;
+
+        #[derive(sqlx::FromRow)]
+        struct MemberRow {
+            username: String,
+            display_name: Option<String>,
+        }
+
+        let rows: Vec<MemberRow> = sqlx::query_as(
+            "SELECT u.username, u.display_name \
+             FROM wk_gp_member gm \
+             INNER JOIN wk_group g ON g.id = gm.gp \
+             INNER JOIN \"user\" u ON u.id = gm.\"user\" \
+             WHERE g.wk = $1 AND g.name = $2 AND g.is_deleted = FALSE",
+        )
+        .bind(wk_id)
+        .bind(group_name)
+        .fetch_all(git.db.reader())
+        .await
+        .map_err(AiError::Database)?;
+
+        let members: Vec<Value> = rows.iter().map(|r| json!({
+            "username": r.username,
+            "display_name": r.display_name,
+        })).collect();
+
+        Ok(json!({ "group": group_name, "members": members, "count": members.len() }))
+    }
+}
diff --git a/lib/service/ai/card.rs b/lib/service/ai/card.rs
new file mode 100644
index 0000000..22574c2
--- /dev/null
+++ b/lib/service/ai/card.rs
@@ -0,0 +1,33 @@
+use crate::AppService;
+use crate::ai::types::AiModelCardResponse;
+use crate::error::AppError;
+use db::sqlx;
+use model::ai::AiModelCardModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_model_card(
+        &self,
+        ctx: &Session,
+        model_id: uuid::Uuid,
+    ) -> Result<Option<AiModelCardResponse>, AppError> {
+        let _user_uid = self.ai_require_login(ctx).await?;
+        self.ai_card_get_inner(model_id).await
+    }
+
+    pub(crate) async fn ai_card_get_inner(
+        &self,
+        model_id: uuid::Uuid,
+    ) -> Result<Option<AiModelCardResponse>, AppError> {
+        let card = sqlx::query_as::<_, AiModelCardModel>(
+            "SELECT model, overview, strengths, limitations, safety_notes, eval_summary, metadata, created_at, updated_at \
+             FROM ai_model_card WHERE model = $1",
+        )
+        .bind(model_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(card.map(AiModelCardResponse::from))
+    }
+}
diff --git a/lib/service/ai/discussion.rs b/lib/service/ai/discussion.rs
new file mode 100644
index 0000000..b028f03
--- /dev/null
+++ b/lib/service/ai/discussion.rs
@@ -0,0 +1,44 @@
+use crate::AppService;
+use crate::ai::types::AiDiscussionResponse;
+use crate::error::AppError;
+use crate::{Pagination, session_user};
+use db::sqlx;
+use model::ai::AiModelDiscussionModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_model_discussions(
+        &self,
+        ctx: &Session,
+        model_id: uuid::Uuid,
+        pagination: Pagination,
+    ) -> Result<Vec<AiDiscussionResponse>, AppError> {
+        let _user_uid = session_user(ctx)?;
+
+        let discussions = sqlx::query_as::<_, AiModelDiscussionModel>(
+            "SELECT id, model, \"user\", parent, body, created_at, updated_at, deleted_at \
+             FROM ai_model_discussion WHERE model = $1 AND deleted_at IS NULL \
+             ORDER BY created_at DESC LIMIT $2 OFFSET $3",
+        )
+        .bind(model_id)
+        .bind(pagination.limit() as i64)
+        .bind(pagination.offset() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for d in discussions {
+            let user = self.users_find_by_id(d.user).await?;
+            results.push(AiDiscussionResponse {
+                id: d.id,
+                author: crate::issues::types::issue_author(user),
+                parent: d.parent,
+                body: d.body,
+                created_at: d.created_at,
+                updated_at: d.updated_at,
+            });
+        }
+        Ok(results)
+    }
+}
diff --git a/lib/service/ai/like.rs b/lib/service/ai/like.rs
new file mode 100644
index 0000000..3e1b645
--- /dev/null
+++ b/lib/service/ai/like.rs
@@ -0,0 +1,49 @@
+use crate::AppService;
+use crate::ai::types::AiLikeResponse;
+use crate::error::AppError;
+use db::sqlx;
+use model::ai::AiModelLikeModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_model_likes(
+        &self,
+        ctx: &Session,
+        model_id: uuid::Uuid,
+    ) -> Result<Vec<AiLikeResponse>, AppError> {
+        let _user_uid = self.ai_require_login(ctx).await?;
+
+        let likes = sqlx::query_as::<_, AiModelLikeModel>(
+            "SELECT model, \"user\", created_at FROM ai_model_like WHERE model = $1 \
+             ORDER BY created_at DESC",
+        )
+        .bind(model_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for l in likes {
+            let user = self.users_find_by_id(l.user).await?;
+            results.push(AiLikeResponse {
+                user: crate::issues::types::issue_author(user),
+                created_at: l.created_at,
+            });
+        }
+        Ok(results)
+    }
+
+    pub(crate) async fn ai_like_count_inner(
+        &self,
+        model_id: uuid::Uuid,
+    ) -> Result<i64, AppError> {
+        let count = sqlx::query_scalar::<_, i64>(
+            "SELECT COUNT(*) FROM ai_model_like WHERE model = $1",
+        )
+        .bind(model_id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(count)
+    }
+}
diff --git a/lib/service/ai/mod.rs b/lib/service/ai/mod.rs
new file mode 100644
index 0000000..3361e6c
--- /dev/null
+++ b/lib/service/ai/mod.rs
@@ -0,0 +1,24 @@
+pub mod card;
+pub mod discussion;
+pub mod like;
+pub mod model;
+pub mod provider;
+pub mod sync;
+pub mod tag;
+pub mod types;
+pub mod version;
+
+use crate::AppService;
+use crate::error::AppError;
+use crate::session_user;
+use session::Session;
+use uuid::Uuid;
+
+impl AppService {
+    pub(crate) async fn ai_require_login(
+        &self,
+        ctx: &Session,
+    ) -> Result<Uuid, AppError> {
+        session_user(ctx)
+    }
+}
diff --git a/lib/service/ai/model.rs b/lib/service/ai/model.rs
new file mode 100644
index 0000000..b495b56
--- /dev/null
+++ b/lib/service/ai/model.rs
@@ -0,0 +1,160 @@
+use crate::AppService;
+use crate::ai::types::{AiModelFilter, AiModelListItem, AiModelResponse};
+use crate::error::AppError;
+use crate::{Pagination, session_user};
+use db::sqlx;
+use db::sqlx::AssertSqlSafe;
+use model::ai::AiModelModel;
+use model::ai::AiProviderModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_model_list(
+        &self,
+        ctx: &Session,
+        filter: AiModelFilter,
+        pagination: Pagination,
+    ) -> Result<Vec<AiModelListItem>, AppError> {
+        let _user_uid = session_user(ctx)?;
+
+        let mut conditions = vec![
+            "m.public = true".to_string(),
+            "m.deleted_at IS NULL".to_string(),
+        ];
+        let mut param_idx = 1;
+
+        if filter.enabled.is_some() {
+            conditions.push(format!("m.enabled = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.provider.is_some() {
+            conditions.push(format!("m.provider = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.modality.is_some() {
+            conditions.push(format!("m.modality = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.name.is_some() {
+            conditions.push(format!("m.name ILIKE ${param_idx}"));
+            param_idx += 1;
+        }
+
+        let where_clause = conditions.join(" AND ");
+        let limit_idx = param_idx;
+        let offset_idx = param_idx + 1;
+
+        let query = format!(
+            "SELECT m.id, m.provider, m.name, m.display_name, m.description, m.modality, \
+             m.context_window, m.input_token_limit, m.output_token_limit, \
+             m.enabled, m.public, m.created_at, m.updated_at, m.deleted_at \
+             FROM ai_model m WHERE {where_clause} \
+             ORDER BY m.display_name ASC LIMIT ${limit_idx} OFFSET ${offset_idx}"
+        );
+
+        let mut q = sqlx::query_as::<_, AiModelModel>(AssertSqlSafe(query));
+        if let Some(enabled) = &filter.enabled {
+            q = q.bind(enabled);
+        }
+        if let Some(provider) = &filter.provider {
+            q = q.bind(provider);
+        }
+        if let Some(modality) = &filter.modality {
+            q = q.bind(modality);
+        }
+        if let Some(name) = &filter.name {
+            q = q.bind(format!("%{}%", name));
+        }
+        q = q
+            .bind(pagination.limit() as i64)
+            .bind(pagination.offset() as i64);
+
+        let models = q
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for m in models {
+            let provider = self.ai_provider_by_id(m.provider).await?;
+            results.push(AiModelListItem {
+                id: m.id,
+                name: m.name,
+                display_name: m.display_name,
+                description: crate::non_empty(
+                    m.description.unwrap_or_default(),
+                ),
+                modality: m.modality,
+                provider_name: provider.name,
+                provider_logo_url: provider.logo_url,
+                context_window: m.context_window,
+                input_token_limit: m.input_token_limit,
+                output_token_limit: m.output_token_limit,
+                enabled: m.enabled,
+                created_at: m.created_at,
+                updated_at: m.updated_at,
+            });
+        }
+        Ok(results)
+    }
+    pub async fn ai_model_get(
+        &self,
+        ctx: &Session,
+        id: uuid::Uuid,
+    ) -> Result<AiModelResponse, AppError> {
+        let _user_uid = session_user(ctx)?;
+
+        let m = sqlx::query_as::<_, AiModelModel>(
+            "SELECT id, provider, name, display_name, description, modality, \
+             context_window, input_token_limit, output_token_limit, \
+             enabled, public, created_at, updated_at, deleted_at \
+             FROM ai_model WHERE id = $1 AND (public = true OR deleted_at IS NULL)",
+        )
+        .bind(id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("model not found".to_string()))?;
+
+        let provider = self.ai_provider_by_id(m.provider).await?;
+        let card = self.ai_card_get_inner(m.id).await?;
+        let versions = self.ai_version_list_inner(m.id).await?;
+        let tags = self.ai_tag_list_inner(m.id).await?;
+        let like_count = self.ai_like_count_inner(m.id).await?;
+
+        Ok(AiModelResponse {
+            id: m.id,
+            name: m.name,
+            display_name: m.display_name,
+            description: crate::non_empty(m.description.unwrap_or_default()),
+            modality: m.modality,
+            context_window: m.context_window,
+            input_token_limit: m.input_token_limit,
+            output_token_limit: m.output_token_limit,
+            enabled: m.enabled,
+            public: m.public,
+            provider_name: provider.name,
+            provider_logo_url: provider.logo_url,
+            card,
+            versions,
+            tags,
+            like_count,
+            created_at: m.created_at,
+            updated_at: m.updated_at,
+        })
+    }
+
+    pub(crate) async fn ai_provider_by_id(
+        &self,
+        id: uuid::Uuid,
+    ) -> Result<AiProviderModel, AppError> {
+        sqlx::query_as::<_, AiProviderModel>(
+            "SELECT id, name, base_url, website_url, logo_url, enabled, created_at, updated_at \
+             FROM ai_provider WHERE id = $1",
+        )
+        .bind(id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))
+    }
+}
diff --git a/lib/service/ai/provider.rs b/lib/service/ai/provider.rs
new file mode 100644
index 0000000..de45160
--- /dev/null
+++ b/lib/service/ai/provider.rs
@@ -0,0 +1,47 @@
+use crate::AppService;
+use crate::ai::types::AiProviderResponse;
+use crate::error::AppError;
+use db::sqlx;
+use model::ai::AiProviderModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_provider_list(
+        &self,
+        ctx: &Session,
+    ) -> Result<Vec<AiProviderResponse>, AppError> {
+        self.ai_require_login(ctx).await?;
+
+        let providers = sqlx::query_as::<_, AiProviderModel>(
+            "SELECT id, name, base_url, website_url, logo_url, enabled, created_at, updated_at \
+             FROM ai_provider WHERE enabled = true ORDER BY name ASC",
+        )
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(providers
+            .into_iter()
+            .map(AiProviderResponse::from)
+            .collect())
+    }
+    pub async fn ai_provider_get(
+        &self,
+        ctx: &Session,
+        id: uuid::Uuid,
+    ) -> Result<AiProviderResponse, AppError> {
+        self.ai_require_login(ctx).await?;
+
+        let provider = sqlx::query_as::<_, AiProviderModel>(
+            "SELECT id, name, base_url, website_url, logo_url, enabled, created_at, updated_at \
+             FROM ai_provider WHERE id = $1",
+        )
+        .bind(id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("provider not found".to_string()))?;
+
+        Ok(AiProviderResponse::from(provider))
+    }
+}
diff --git a/lib/service/ai/sync.rs b/lib/service/ai/sync.rs
new file mode 100644
index 0000000..ecc1c1e
--- /dev/null
+++ b/lib/service/ai/sync.rs
@@ -0,0 +1,585 @@
+use std::time::Duration;
+
+use ai::sync::{UpstreamModel, UpstreamPricing};
+use ai::client::EndpointConfig;
+use chrono::Utc;
+use db::sqlx::{self, types::Decimal};
+use model::ai::{AiModelModel, AiModelVersionModel, AiProviderModel};
+use serde::Serialize;
+use tokio::time::interval;
+use utoipa::ToSchema;
+use uuid::Uuid;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Serialize, ToSchema)]
+pub struct SyncModelsResponse {
+    pub models_created: i64,
+    pub models_updated: i64,
+    pub models_offline: i64,
+    pub models_deactivated: i64,
+    pub versions_created: i64,
+    pub pricing_created: i64,
+    pub pricing_updated: i64,
+}
+
+#[derive(Debug, Clone)]
+pub struct SyncResult {
+    pub provider_id: Uuid,
+    pub provider_name: String,
+    pub total: u32,
+    pub synced: u32,
+    pub skipped: u32,
+}
+
+fn extract_provider_name(model: &UpstreamModel) -> String {
+    if let Some(owned) = &model.owned_by {
+        if !owned.is_empty() {
+            return normalize_provider_name(owned);
+        }
+    }
+    normalize_provider_name(model.id.split('/').next().unwrap_or("unknown"))
+}
+
+fn normalize_provider_name(slug: &str) -> String {
+    match slug {
+        "openai" => "openai",
+        "anthropic" => "anthropic",
+        "google" | "google-ai" => "google",
+        "mistralai" => "mistral",
+        "meta-llama" | "meta" => "meta",
+        "deepseek" => "deepseek",
+        "azure" | "azure-openai" => "azure",
+        "x-ai" | "xai" => "xai",
+        "moonshot" => "moonshot",
+        "alibaba" | "qwen" => "qwen",
+        s => s,
+    }
+    .to_string()
+}
+
+fn provider_display_name(name: &str) -> String {
+    match name {
+        "openai" => "OpenAI",
+        "anthropic" => "Anthropic",
+        "google" => "Google DeepMind",
+        "mistral" => "Mistral AI",
+        "meta" => "Meta",
+        "deepseek" => "DeepSeek",
+        "azure" => "Microsoft Azure",
+        "xai" => "xAI",
+        "moonshot" => "Moonshot AI",
+        "qwen" => "Alibaba Qwen",
+        s => s,
+    }
+    .to_string()
+}
+
+fn infer_modality(model: &UpstreamModel) -> &'static str {
+    if let Some(caps) = &model.capabilities {
+        if caps.vision == Some(true) {
+            return "multimodal";
+        }
+    }
+    let lower = model.id.to_lowercase();
+    if lower.contains("vision")
+        || lower.contains("dall-e")
+        || lower.contains("gpt-image")
+        || lower.contains("gpt-4o")
+    {
+        "multimodal"
+    } else if lower.contains("embedding") {
+        "text"
+    } else if lower.contains("whisper") || lower.contains("audio") {
+        "audio"
+    } else {
+        "text"
+    }
+}
+
+async fn upsert_provider(
+    db: &db::AppDatabase,
+    slug: &str,
+) -> Result<AiProviderModel, AppError> {
+    let _display = provider_display_name(slug);
+    let now = Utc::now();
+
+    if let Some(existing) = sqlx::query_as::<_, AiProviderModel>(
+        "SELECT id, name, base_url, website_url, logo_url, enabled, created_at, updated_at \
+         FROM ai_provider WHERE name = $1",
+    )
+    .bind(slug)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?
+    {
+        sqlx::query(
+            "UPDATE ai_provider SET updated_at = $1 WHERE id = $2",
+        )
+        .bind(now)
+        .bind(existing.id)
+        .execute(db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(existing)
+    } else {
+        let id = Uuid::now_v7();
+        sqlx::query(
+            "INSERT INTO ai_provider (id, name, enabled, created_at, updated_at) \
+             VALUES ($1, $2, true, $3, $3)",
+        )
+        .bind(id)
+        .bind(slug)
+        .bind(now)
+        .execute(db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(AiProviderModel {
+            id,
+            name: slug.to_string(),
+            base_url: None,
+            website_url: None,
+            logo_url: None,
+            enabled: true,
+            created_at: now,
+            updated_at: now,
+        })
+    }
+}
+
+async fn upsert_model(
+    db: &db::AppDatabase,
+    provider_id: Uuid,
+    model: &UpstreamModel,
+) -> Result<(AiModelModel, bool), AppError> {
+    let now = Utc::now();
+    let name = &model.id;
+    let modality = infer_modality(model);
+    let ctx = model.context_length.map(|c| c as i32);
+    let max_out = model.max_output_tokens.map(|v| v as i32);
+
+    if let Some(existing) = sqlx::query_as::<_, AiModelModel>(
+        "SELECT id, provider, name, display_name, description, modality, \
+         context_window, input_token_limit, output_token_limit, \
+         enabled, public, created_at, updated_at, deleted_at \
+         FROM ai_model WHERE name = $1 AND deleted_at IS NULL",
+    )
+    .bind(name)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?
+    {
+        sqlx::query(
+            "UPDATE ai_model SET provider = $1, context_window = $2, \
+             output_token_limit = $3, enabled = true, updated_at = $4 \
+             WHERE id = $5",
+        )
+        .bind(provider_id)
+        .bind(ctx)
+        .bind(max_out)
+        .bind(now)
+        .bind(existing.id)
+        .execute(db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok((existing, false))
+    } else {
+        let id = Uuid::now_v7();
+        sqlx::query(
+            "INSERT INTO ai_model (id, provider, name, display_name, modality, \
+             context_window, input_token_limit, output_token_limit, enabled, \
+             public, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, true, true, $9, $9)",
+        )
+        .bind(id)
+        .bind(provider_id)
+        .bind(name)
+        .bind(name)
+        .bind(modality)
+        .bind(ctx)
+        .bind(ctx)
+        .bind(max_out)
+        .bind(now)
+        .execute(db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let inserted = sqlx::query_as::<_, AiModelModel>(
+            "SELECT id, provider, name, display_name, description, modality, \
+             context_window, input_token_limit, output_token_limit, \
+             enabled, public, created_at, updated_at, deleted_at \
+             FROM ai_model WHERE id = $1",
+        )
+        .bind(id)
+        .fetch_one(db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok((inserted, true))
+    }
+}
+
+async fn upsert_version(
+    db: &db::AppDatabase,
+    model_id: Uuid,
+    provider_model_name: &str,
+) -> Result<(AiModelVersionModel, bool), AppError> {
+    let now = Utc::now();
+
+    if let Some(existing) = sqlx::query_as::<_, AiModelVersionModel>(
+        "SELECT id, model, version, provider_model_name, \
+         input_price_per_million, output_price_per_million, cached_input_price_per_million, \
+         training_cutoff, released_at, deprecated_at, enabled, created_at, updated_at \
+         FROM ai_model_version WHERE model = $1 AND provider_model_name = $2",
+    )
+    .bind(model_id)
+    .bind(provider_model_name)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?
+    {
+        Ok((existing, false))
+    } else {
+        let id = Uuid::now_v7();
+        sqlx::query(
+            "INSERT INTO ai_model_version (id, model, version, provider_model_name, \
+             enabled, created_at, updated_at) \
+             VALUES ($1, $2, 'latest', $3, true, $4, $4)",
+        )
+        .bind(id)
+        .bind(model_id)
+        .bind(provider_model_name)
+        .bind(now)
+        .execute(db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let inserted = sqlx::query_as::<_, AiModelVersionModel>(
+            "SELECT id, model, version, provider_model_name, \
+             input_price_per_million, output_price_per_million, cached_input_price_per_million, \
+             training_cutoff, released_at, deprecated_at, enabled, created_at, updated_at \
+             FROM ai_model_version WHERE id = $1",
+        )
+        .bind(id)
+        .fetch_one(db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok((inserted, true))
+    }
+}
+
+async fn upsert_pricing(
+    db: &db::AppDatabase,
+    version_id: Uuid,
+    pricing: Option<&UpstreamPricing>,
+) -> Result<PricingResult, AppError> {
+    let Some(p) = pricing else {
+        return Ok(PricingResult::Skipped);
+    };
+    let input_million: Option<Decimal> = p.prompt.as_deref().and_then(parse_token_price_decimal)
+        .map(|per_token| per_token * Decimal::from(1_000_000u64))
+        .or_else(|| {
+            p.input
+                .filter(|v| *v > 0.0)
+                .map(|v| Decimal::try_from(v).unwrap_or_default())
+        });
+
+    let output_million: Option<Decimal> = p.completion.as_deref().and_then(parse_token_price_decimal)
+        .map(|per_token| per_token * Decimal::from(1_000_000u64))
+        .or_else(|| {
+            p.output
+                .filter(|v| *v > 0.0)
+                .map(|v| Decimal::try_from(v).unwrap_or_default())
+        });
+
+    let cache_input: Option<Decimal> = p.cache_read
+        .filter(|v| *v > 0.0)
+        .map(|v| Decimal::try_from(v).unwrap_or_default());
+
+    if input_million.is_none() && output_million.is_none() {
+        return Ok(PricingResult::Skipped);
+    }
+
+    let existing = sqlx::query_scalar::<_, Uuid>(
+        "SELECT id FROM ai_model_version WHERE id = $1",
+    )
+    .bind(version_id)
+    .fetch_optional(db.reader())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+    if existing.is_none() {
+        return Ok(PricingResult::Skipped);
+    }
+
+    let count = sqlx::query_scalar::<_, i64>(
+        "SELECT COUNT(*) FROM ai_model_version \
+         WHERE id = $1 AND input_price_per_million IS NOT NULL",
+    )
+    .bind(version_id)
+    .fetch_one(db.reader())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+    sqlx::query(
+        "UPDATE ai_model_version SET \
+         input_price_per_million = COALESCE($1, input_price_per_million), \
+         output_price_per_million = COALESCE($2, output_price_per_million), \
+         cached_input_price_per_million = COALESCE($3, cached_input_price_per_million), \
+         updated_at = $4 \
+         WHERE id = $5",
+    )
+    .bind(&input_million)
+    .bind(&output_million)
+    .bind(&cache_input)
+    .bind(Utc::now())
+    .bind(version_id)
+    .execute(db.writer())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+    if count > 0 {
+        Ok(PricingResult::Updated)
+    } else {
+        Ok(PricingResult::Created)
+    }
+}
+
+enum PricingResult {
+    Created,
+    Updated,
+    Skipped,
+}
+
+fn parse_token_price_decimal(s: &str) -> Option<Decimal> {
+    use std::str::FromStr;
+    Decimal::from_str(s).ok()
+}
+
+async fn disable_all_models(db: &db::AppDatabase) -> Result<i64, AppError> {
+    let result = sqlx::query(
+        "UPDATE ai_model SET enabled = false, updated_at = $1 WHERE enabled = true",
+    )
+    .bind(Utc::now())
+    .execute(db.writer())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+    Ok(result.rows_affected() as i64)
+}
+
+async fn deactivate_orphaned_models(db: &db::AppDatabase) -> Result<i64, AppError> {
+    let now = Utc::now();
+    sqlx::query(
+        "UPDATE ai_model_version SET enabled = false, updated_at = $1 \
+         WHERE model IN (SELECT id FROM ai_model WHERE enabled = false AND deleted_at IS NULL)",
+    )
+    .bind(now)
+    .execute(db.writer())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+    let result = sqlx::query(
+        "UPDATE ai_model SET deleted_at = $1, updated_at = $1 \
+         WHERE enabled = false AND deleted_at IS NULL",
+    )
+    .bind(now)
+    .execute(db.writer())
+    .await
+    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+    Ok(result.rows_affected() as i64)
+}
+
+async fn sync_models_from_upstream(
+    db: &db::AppDatabase,
+    upstream_models: Vec<UpstreamModel>,
+) -> SyncModelsResponse {
+    let models_offline = disable_all_models(db).await.unwrap_or(0);
+
+    tracing::info!(
+        upstream_total = upstream_models.len(),
+        "syncing models from upstream"
+    );
+
+    let mut models_created = 0i64;
+    let mut models_updated = 0i64;
+    let mut versions_created = 0i64;
+    let mut pricing_created = 0i64;
+    let mut pricing_updated = 0i64;
+
+    for model in &upstream_models {
+        let provider_slug = extract_provider_name(model);
+        let provider = match upsert_provider(db, &provider_slug).await {
+            Ok(p) => p,
+            Err(e) => {
+                tracing::warn!(
+                    provider = %provider_slug,
+                    error = %e,
+                    "sync: upsert_provider error"
+                );
+                continue;
+            }
+        };
+
+        let (model_record, _is_new) = match upsert_model(db, provider.id, model).await {
+            Ok((m, created)) => {
+                if created {
+                    models_created += 1;
+                } else {
+                    models_updated += 1;
+                }
+                (m, created)
+            }
+            Err(e) => {
+                tracing::warn!(
+                    model = %model.id,
+                    error = %e,
+                    "sync: upsert_model error"
+                );
+                continue;
+            }
+        };
+
+        let (version_record, version_is_new) =
+            match upsert_version(db, model_record.id, &model.id).await {
+                Ok(v) => v,
+                Err(e) => {
+                    tracing::warn!(
+                        model = %model.id,
+                        error = %e,
+                        "sync: upsert_version error"
+                    );
+                    continue;
+                }
+            };
+        if version_is_new {
+            versions_created += 1;
+        }
+
+        match upsert_pricing(db, version_record.id, model.pricing.as_ref()).await {
+            Ok(PricingResult::Created) => pricing_created += 1,
+            Ok(PricingResult::Updated) => pricing_updated += 1,
+            Ok(PricingResult::Skipped) => {}
+            Err(e) => {
+                tracing::warn!(
+                    model = %model.id,
+                    error = %e,
+                    "sync: upsert_pricing error"
+                );
+            }
+        }
+    }
+
+    let deactivated = deactivate_orphaned_models(db).await.unwrap_or(0);
+
+    SyncModelsResponse {
+        models_created,
+        models_updated,
+        models_offline,
+        models_deactivated: deactivated,
+        versions_created,
+        pricing_created,
+        pricing_updated,
+    }
+}
+
+impl AppService {
+    pub async fn sync_upstream_models(&self) -> Result<SyncModelsResponse, AppError> {
+        let api_key = self
+            .config
+            .ai_api_key()
+            .map_err(|e| AppError::InternalServerError(format!("AI API key not configured: {}", e)))?;
+
+        let base_url = self.config.ai_basic_url().unwrap_or_default();
+
+        let config = EndpointConfig::new(&base_url, &api_key)
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let upstream_models = ai::sync::list_models(&config)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        tracing::info!(
+            model_count = upstream_models.len(),
+            "sync_upstream_models: {} models from upstream",
+            upstream_models.len()
+        );
+
+        let result = sync_models_from_upstream(&self.db, upstream_models).await;
+
+        tracing::info!(
+            models_created = result.models_created,
+            models_updated = result.models_updated,
+            versions_created = result.versions_created,
+            pricing_created = result.pricing_created,
+            pricing_updated = result.pricing_updated,
+            "sync_upstream_models: complete"
+        );
+
+        Ok(result)
+    }
+}
+
+pub fn spawn_model_sync_loop(service: AppService) -> tokio::task::JoinHandle<()> {
+    let db = service.db.clone();
+    let config = service.config.clone();
+
+    tokio::spawn(async move {
+        sync_once(&db, &config).await;
+
+        let mut tick = interval(Duration::from_secs(60 * 10));
+        loop {
+            tick.tick().await;
+            sync_once(&db, &config).await;
+        }
+    })
+}
+
+async fn sync_once(db: &db::AppDatabase, config: &config::AppConfig) {
+    let api_key = match config.ai_api_key() {
+        Ok(k) => k,
+        Err(e) => {
+            tracing::warn!(error = %e, "Model sync: AI API key not configured");
+            return;
+        }
+    };
+
+    let base_url = config.ai_basic_url().unwrap_or_default();
+
+    let endpoint_config = match EndpointConfig::new(&base_url, &api_key) {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::warn!(error = %e, "Model sync: invalid endpoint config");
+            return;
+        }
+    };
+
+    let upstream_models = match ai::sync::list_models(&endpoint_config).await {
+        Ok(models) => models,
+        Err(e) => {
+            tracing::warn!(error = %e, "Model sync: failed to list upstream models");
+            return;
+        }
+    };
+
+    tracing::info!(
+        model_count = upstream_models.len(),
+        "Model sync: {} models from upstream",
+        upstream_models.len()
+    );
+
+    let result = sync_models_from_upstream(db, upstream_models).await;
+
+    tracing::info!(
+        models_created = result.models_created,
+        models_updated = result.models_updated,
+        versions_created = result.versions_created,
+        pricing_created = result.pricing_created,
+        pricing_updated = result.pricing_updated,
+        "Model sync complete"
+    );
+}
diff --git a/lib/service/ai/tag.rs b/lib/service/ai/tag.rs
new file mode 100644
index 0000000..70d9f4b
--- /dev/null
+++ b/lib/service/ai/tag.rs
@@ -0,0 +1,31 @@
+use crate::AppService;
+use crate::error::AppError;
+use db::sqlx;
+use model::ai::AiModelModelTagModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_model_tags(
+        &self,
+        ctx: &Session,
+        model_id: uuid::Uuid,
+    ) -> Result<Vec<String>, AppError> {
+        let _user_uid = self.ai_require_login(ctx).await?;
+        self.ai_tag_list_inner(model_id).await
+    }
+
+    pub(crate) async fn ai_tag_list_inner(
+        &self,
+        model_id: uuid::Uuid,
+    ) -> Result<Vec<String>, AppError> {
+        let tags = sqlx::query_as::<_, AiModelModelTagModel>(
+            "SELECT model, tag, created_at FROM ai_model_model_tag WHERE model = $1 ORDER BY tag ASC",
+        )
+        .bind(model_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(tags.into_iter().map(|t| t.tag).collect())
+    }
+}
diff --git a/lib/service/ai/types.rs b/lib/service/ai/types.rs
new file mode 100644
index 0000000..555cd28
--- /dev/null
+++ b/lib/service/ai/types.rs
@@ -0,0 +1,170 @@
+use crate::issues::types::IssueAuthor;
+use crate::non_empty;
+use model::ai::*;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiProviderResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+    pub base_url: Option<String>,
+    pub website_url: Option<String>,
+    pub logo_url: Option<String>,
+    pub enabled: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl From<AiProviderModel> for AiProviderResponse {
+    fn from(p: AiProviderModel) -> Self {
+        AiProviderResponse {
+            id: p.id,
+            name: p.name,
+            base_url: non_empty(p.base_url.unwrap_or_default()),
+            website_url: non_empty(p.website_url.unwrap_or_default()),
+            logo_url: non_empty(p.logo_url.unwrap_or_default()),
+            enabled: p.enabled,
+            created_at: p.created_at,
+            updated_at: p.updated_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiModelListItem {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+    pub display_name: String,
+    pub description: Option<String>,
+    pub modality: String,
+    pub provider_name: String,
+    pub provider_logo_url: Option<String>,
+    pub context_window: Option<i32>,
+    pub input_token_limit: Option<i32>,
+    pub output_token_limit: Option<i32>,
+    pub enabled: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiModelResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+    pub display_name: String,
+    pub description: Option<String>,
+    pub modality: String,
+    pub context_window: Option<i32>,
+    pub input_token_limit: Option<i32>,
+    pub output_token_limit: Option<i32>,
+    pub enabled: bool,
+    pub public: bool,
+    pub provider_name: String,
+    pub provider_logo_url: Option<String>,
+    pub card: Option<AiModelCardResponse>,
+    pub versions: Vec<AiModelVersionResponse>,
+    pub tags: Vec<String>,
+    pub like_count: i64,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiModelCardResponse {
+    pub overview: Option<String>,
+    pub strengths: Option<String>,
+    pub limitations: Option<String>,
+    pub safety_notes: Option<String>,
+    pub eval_summary: Option<String>,
+    pub metadata: Option<String>,
+}
+
+impl From<AiModelCardModel> for AiModelCardResponse {
+    fn from(c: AiModelCardModel) -> Self {
+        AiModelCardResponse {
+            overview: non_empty(c.overview.unwrap_or_default()),
+            strengths: non_empty(c.strengths.unwrap_or_default()),
+            limitations: non_empty(c.limitations.unwrap_or_default()),
+            safety_notes: non_empty(c.safety_notes.unwrap_or_default()),
+            eval_summary: non_empty(c.eval_summary.unwrap_or_default()),
+            metadata: non_empty(c.metadata.unwrap_or_default()),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiModelVersionResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub version: String,
+    pub provider_model_name: String,
+    pub input_price_per_million: Option<String>,
+    pub output_price_per_million: Option<String>,
+    pub cached_input_price_per_million: Option<String>,
+    pub training_cutoff: Option<String>,
+    #[schema(value_type = Option<String>)]
+    pub released_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = Option<String>)]
+    pub deprecated_at: Option<chrono::DateTime<chrono::Utc>>,
+    pub enabled: bool,
+}
+
+impl From<AiModelVersionModel> for AiModelVersionResponse {
+    fn from(v: AiModelVersionModel) -> Self {
+        AiModelVersionResponse {
+            id: v.id,
+            version: v.version,
+            provider_model_name: v.provider_model_name,
+            input_price_per_million: v
+                .input_price_per_million
+                .map(|d| d.to_string()),
+            output_price_per_million: v
+                .output_price_per_million
+                .map(|d| d.to_string()),
+            cached_input_price_per_million: v
+                .cached_input_price_per_million
+                .map(|d| d.to_string()),
+            training_cutoff: v.training_cutoff,
+            released_at: v.released_at,
+            deprecated_at: v.deprecated_at,
+            enabled: v.enabled,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiDiscussionResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub author: IssueAuthor,
+    pub parent: Option<uuid::Uuid>,
+    pub body: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AiLikeResponse {
+    pub user: IssueAuthor,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::IntoParams)]
+pub struct AiModelFilter {
+    pub enabled: Option<bool>,
+    pub provider: Option<uuid::Uuid>,
+    pub modality: Option<String>,
+    pub name: Option<String>,
+}
diff --git a/lib/service/ai/version.rs b/lib/service/ai/version.rs
new file mode 100644
index 0000000..1f6ac52
--- /dev/null
+++ b/lib/service/ai/version.rs
@@ -0,0 +1,40 @@
+use crate::AppService;
+use crate::ai::types::AiModelVersionResponse;
+use crate::error::AppError;
+use db::sqlx;
+use model::ai::AiModelVersionModel;
+use session::Session;
+
+impl AppService {
+    pub async fn ai_model_versions(
+        &self,
+        ctx: &Session,
+        model_id: uuid::Uuid,
+    ) -> Result<Vec<AiModelVersionResponse>, AppError> {
+        let _user_uid = self.ai_require_login(ctx).await?;
+
+        self.ai_version_list_inner(model_id).await
+    }
+
+    pub(crate) async fn ai_version_list_inner(
+        &self,
+        model_id: uuid::Uuid,
+    ) -> Result<Vec<AiModelVersionResponse>, AppError> {
+        let versions = sqlx::query_as::<_, AiModelVersionModel>(
+            "SELECT id, model, version, provider_model_name, \
+             input_price_per_million, output_price_per_million, cached_input_price_per_million, \
+             training_cutoff, released_at, deprecated_at, enabled, created_at, updated_at \
+             FROM ai_model_version WHERE model = $1 AND enabled = true \
+             ORDER BY released_at DESC",
+        )
+        .bind(model_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(versions
+            .into_iter()
+            .map(AiModelVersionResponse::from)
+            .collect())
+    }
+}
diff --git a/lib/service/auth/captcha.rs b/lib/service/auth/captcha.rs
new file mode 100644
index 0000000..e655a7e
--- /dev/null
+++ b/lib/service/auth/captcha.rs
@@ -0,0 +1,72 @@
+use session::Session;
+use utoipa::{IntoParams, ToSchema};
+
+use crate::{
+    AppService, auth::rsa::RsaResponse, constant_time_eq, error::AppError,
+};
+
+#[derive(
+    serde::Deserialize, serde::Serialize, Clone, Debug, ToSchema, IntoParams,
+)]
+pub struct CaptchaQuery {
+    pub w: u32,
+    pub h: u32,
+    pub dark: bool,
+    pub rsa: bool,
+}
+
+#[derive(serde::Serialize, ToSchema)]
+pub struct CaptchaResponse {
+    pub base64: String,
+    pub rsa: Option<RsaResponse>,
+    pub req: CaptchaQuery,
+}
+
+impl AppService {
+    const CAPTCHA_KEY: &'static str = "captcha";
+    const CAPTCHA_LENGTH: usize = 4;
+    pub async fn auth_captcha(
+        &self,
+        context: &Session,
+        query: CaptchaQuery,
+    ) -> Result<CaptchaResponse, AppError> {
+        let CaptchaQuery { w, h, dark, rsa } = query;
+        let captcha = captcha_rs::CaptchaBuilder::new()
+            .width(w)
+            .height(h)
+            .dark_mode(dark)
+            .length(Self::CAPTCHA_LENGTH)
+            .build();
+
+        let base64 = captcha.to_base64();
+
+        let text = captcha.text;
+        context.insert(Self::CAPTCHA_KEY, text).ok();
+        Ok(CaptchaResponse {
+            base64,
+            rsa: if rsa {
+                Some(self.auth_rsa(context).await?)
+            } else {
+                None
+            },
+            req: CaptchaQuery { w, h, dark, rsa },
+        })
+    }
+    pub async fn auth_check_captcha(
+        &self,
+        context: &Session,
+        captcha: String,
+    ) -> Result<(), AppError> {
+        let text = context
+            .get::<String>(Self::CAPTCHA_KEY)
+            .map_err(|_| AppError::CaptchaError)?
+            .ok_or(AppError::CaptchaError)?;
+        if !constant_time_eq(&text.to_lowercase(), &captcha.to_lowercase()) {
+            context.remove(Self::CAPTCHA_KEY);
+            tracing::warn!(ip = ?context.ip_address(), "Captcha verification failed");
+            return Err(AppError::CaptchaError);
+        }
+        context.remove(Self::CAPTCHA_KEY);
+        Ok(())
+    }
+}
diff --git a/lib/service/auth/email.rs b/lib/service/auth/email.rs
new file mode 100644
index 0000000..d17c1bc
--- /dev/null
+++ b/lib/service/auth/email.rs
@@ -0,0 +1,197 @@
+use argon2::{Argon2, PasswordHash, password_hash::PasswordVerifier};
+use db::sqlx;
+use email::EmailMessage;
+use model::users::{UserEmailModel, user_pass::UserPasswordModel};
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Deserialize, Serialize, utoipa::ToSchema)]
+pub struct EmailChangeRequest {
+    pub new_email: String,
+    pub password: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, utoipa::ToSchema)]
+pub struct EmailVerifyRequest {
+    pub token: String,
+}
+
+#[derive(Debug, Clone, Serialize, utoipa::ToSchema)]
+pub struct EmailResponse {
+    pub email: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+struct PendingEmailChange {
+    user_uid: uuid::Uuid,
+    new_email: String,
+}
+
+impl AppService {
+    const EMAIL_CHANGE_PREFIX: &'static str = "auth:email_change:";
+
+    pub async fn auth_get_email(
+        &self,
+        ctx: &Session,
+    ) -> Result<EmailResponse, AppError> {
+        let user_uid = ctx.user().ok_or(AppError::Unauthorized)?;
+        let email = sqlx::query_as::<_, UserEmailModel>(
+            "SELECT \"user\", email, created_at, active, last_use_login, updated_at \
+             FROM user_email WHERE \"user\" = $1 AND active = true",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(EmailResponse {
+            email: email.map(|e| e.email),
+        })
+    }
+
+    pub async fn auth_email_change_request(
+        &self,
+        ctx: &Session,
+        params: EmailChangeRequest,
+    ) -> Result<(), AppError> {
+        let user_uid = ctx.user().ok_or(AppError::Unauthorized)?;
+        let password = self.auth_rsa_decode(ctx, params.password).await?;
+
+        let user_password = sqlx::query_as::<_, UserPasswordModel>(
+            "SELECT \"user\", hash, salt, is_active, reason, created_at, updated_at \
+             FROM user_password WHERE \"user\" = $1 AND is_active = true",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        let hash = PasswordHash::new(&user_password.hash)
+            .map_err(|_| AppError::UserNotFound)?;
+        Argon2::default()
+            .verify_password(password.as_bytes(), &hash)
+            .map_err(|_| AppError::InvalidPassword)?;
+
+        let existing = sqlx::query_as::<_, UserEmailModel>(
+            "SELECT \"user\", email, created_at, active, last_use_login, updated_at \
+             FROM user_email WHERE email = $1 AND active = true",
+        )
+        .bind(&params.new_email)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        if existing.is_some() {
+            return Err(AppError::EmailExists);
+        }
+
+        let token = Self::generate_email_change_token();
+        let cache_key = format!("{}{}", Self::EMAIL_CHANGE_PREFIX, token);
+        self.cache
+            .set(
+                &cache_key,
+                &PendingEmailChange {
+                    user_uid,
+                    new_email: params.new_email.clone(),
+                },
+            )
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let domain = self
+            .config
+            .main_domain()
+            .map_err(|_| AppError::DoMainNotSet)?;
+        let verify_link =
+            format!("{}/auth/verify-email?token={}", domain, token);
+
+        self.email
+            .send(EmailMessage {
+                to: params.new_email.clone(),
+                subject: "Confirm Email Change".to_string(),
+                body: format!(
+                    "You requested to change your GitDataAI email address.\n\n\
+                     Confirm the change here:\n\n{}\n\n\
+                     If you did not request this change, ignore this email.",
+                    verify_link
+                ),
+            })
+            .await
+            .map_err(|e| {
+                tracing::error!(error = %e, new_email = %params.new_email, "Failed to queue email change verification");
+                AppError::InternalServerError(e.to_string())
+            })?;
+
+        tracing::info!(new_email = %params.new_email, user_uid = %user_uid, "Email change verification queued");
+        Ok(())
+    }
+
+    pub async fn auth_email_verify(
+        &self,
+        params: EmailVerifyRequest,
+    ) -> Result<(), AppError> {
+        if params.token.is_empty() {
+            return Err(AppError::BadRequest(
+                "missing email verification token".to_string(),
+            ));
+        }
+        let cache_key =
+            format!("{}{}", Self::EMAIL_CHANGE_PREFIX, params.token);
+        let pending = self
+            .cache
+            .get::<PendingEmailChange>(&cache_key)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?
+            .ok_or(AppError::NotFound(
+                "invalid or expired email verification token".to_string(),
+            ))?;
+
+        let existing = sqlx::query_as::<_, UserEmailModel>(
+            "SELECT \"user\", email, created_at, active, last_use_login, updated_at \
+             FROM user_email WHERE email = $1 AND active = true",
+        )
+        .bind(&pending.new_email)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        if existing.is_some() {
+            return Err(AppError::EmailExists);
+        }
+
+        let now = chrono::Utc::now();
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+        sqlx::query("UPDATE user_email SET active = false, updated_at = $1 WHERE \"user\" = $2")
+            .bind(now)
+            .bind(pending.user_uid)
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        sqlx::query(
+            "INSERT INTO user_email (\"user\", email, created_at, active, last_use_login, updated_at) \
+             VALUES ($1, $2, $3, true, NULL, $3)",
+        )
+        .bind(pending.user_uid)
+        .bind(&pending.new_email)
+        .bind(now)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+
+        let _ = self.cache.remove(&cache_key).await;
+        tracing::info!(new_email = %pending.new_email, user_uid = %pending.user_uid, "Email changed successfully");
+        Ok(())
+    }
+
+    fn generate_email_change_token() -> String {
+        use rand::{RngExt, distr::Alphanumeric};
+
+        #[allow(deprecated)]
+        let mut rng = rand::rng();
+        let token: String =
+            (0..64).map(|_| rng.sample(Alphanumeric) as char).collect();
+        format!("emc_{}", token)
+    }
+}
diff --git a/lib/service/auth/login.rs b/lib/service/auth/login.rs
new file mode 100644
index 0000000..903e3bc
--- /dev/null
+++ b/lib/service/auth/login.rs
@@ -0,0 +1,171 @@
+use argon2::{
+    Argon2, PasswordHash,
+    password_hash::{PasswordHasher, PasswordVerifier},
+};
+use db::sqlx;
+use model::users::{UserModel, user_pass::UserPasswordModel};
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct LoginParams {
+    pub username: String,
+    pub password: String,
+    pub captcha: String,
+    pub totp_code: Option<String>,
+}
+
+impl AppService {
+    pub const TOTP_KEY: &'static str = "totp_key";
+    pub async fn auth_login(
+        &self,
+        params: LoginParams,
+        context: Session,
+    ) -> Result<(), AppError> {
+        self.auth_check_captcha(&context, params.captcha).await?;
+        let password = self.auth_rsa_decode(&context, params.password).await?;
+        let user = match self.auth_find_user_by_username(&params.username).await
+        {
+            Ok(user) => user,
+            Err(_) => {
+                match self.auth_find_user_by_email(&params.username).await {
+                    Ok(user) => user,
+                    Err(_) => {
+                        let _ = Argon2::default()
+                            .hash_password(password.as_bytes());
+                        return Err(AppError::UserNotFound);
+                    }
+                }
+            }
+        };
+
+        let user_password = sqlx::query_as::<_, UserPasswordModel>(
+            "SELECT \"user\", hash, salt, is_active, reason, created_at, updated_at \
+             FROM user_password WHERE \"user\" = $1 AND is_active = true",
+        )
+        .bind(user.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        let password_hash = PasswordHash::new(&user_password.hash)
+            .map_err(|_| AppError::UserNotFound)?;
+        if Argon2::default()
+            .verify_password(password.as_bytes(), &password_hash)
+            .is_err()
+        {
+            tracing::warn!(username = %params.username, ip = ?context.ip_address(), "Login failed: invalid password");
+            return Err(AppError::UserNotFound);
+        }
+
+        if context
+            .get::<String>(Self::TOTP_KEY)
+            .ok()
+            .flatten()
+            .is_some()
+        {
+            if let Some(ref totp_code) = params.totp_code {
+                if !self.auth_2fa_verify_login(&context, totp_code).await? {
+                    return Err(AppError::InvalidTwoFactorCode);
+                }
+            } else {
+                return Err(AppError::InvalidTwoFactorCode);
+            }
+        } else if self.auth_2fa_status_by_uid(user.id).await?.is_enabled {
+            let totp_session_key = uuid::Uuid::new_v4().to_string();
+            context
+                .insert(Self::TOTP_KEY, totp_session_key.clone())
+                .map_err(|_| AppError::InternalError)?;
+            self.cache
+                .set(&totp_session_key, &user.id)
+                .await
+                .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+            tracing::info!(username = %params.username, ip = ?context.ip_address(), "Login 2FA triggered");
+            return Err(AppError::TwoFactorRequired);
+        }
+
+        sqlx::query("UPDATE \"user\" SET last_sign_in_at = $1, updated_at = $1 WHERE id = $2")
+            .bind(chrono::Utc::now())
+            .bind(user.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        context.renew();
+        context.set_user(user.id);
+        context.remove(Self::RSA_PRIVATE_KEY);
+        context.remove(Self::RSA_PUBLIC_KEY);
+        tracing::info!(user_uid = %user.id, username = %user.username, ip = ?context.ip_address(), "User logged in successfully");
+        Ok(())
+    }
+
+    pub(crate) async fn auth_find_user_by_username(
+        &self,
+        username: &str,
+    ) -> Result<UserModel, AppError> {
+        sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+                    last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE username = $1",
+        )
+        .bind(username)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)
+    }
+
+    pub(crate) async fn auth_find_user_by_email(
+        &self,
+        email: &str,
+    ) -> Result<UserModel, AppError> {
+        sqlx::query_as::<_, UserModel>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, \
+                    u.can_search, u.last_sign_in_at, u.created_at, u.updated_at \
+             FROM \"user\" u \
+             INNER JOIN user_email e ON e.\"user\" = u.id \
+             WHERE e.email = $1 AND e.active = true",
+        )
+        .bind(email)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)
+    }
+
+    pub(crate) async fn auth_find_user_by_uid(
+        &self,
+        uid: uuid::Uuid,
+    ) -> Result<UserModel, AppError> {
+        sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+                    last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE id = $1",
+        )
+        .bind(uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)
+    }
+
+    pub(crate) fn validate_password_strength(
+        password: &str,
+    ) -> Result<(), AppError> {
+        if password.len() < 8 {
+            return Err(AppError::PasswordTooWeak);
+        }
+
+        let has_uppercase = password.chars().any(|c| c.is_uppercase());
+        let has_lowercase = password.chars().any(|c| c.is_lowercase());
+        let has_digit = password.chars().any(|c| c.is_numeric());
+
+        if !has_uppercase || !has_lowercase || !has_digit {
+            return Err(AppError::PasswordTooWeak);
+        }
+        Ok(())
+    }
+}
diff --git a/lib/service/auth/logout.rs b/lib/service/auth/logout.rs
new file mode 100644
index 0000000..bc04c23
--- /dev/null
+++ b/lib/service/auth/logout.rs
@@ -0,0 +1,14 @@
+use session::Session;
+
+use crate::{AppService, error::AppError};
+
+impl AppService {
+    pub async fn auth_logout(&self, context: &Session) -> Result<(), AppError> {
+        if let Some(user_uid) = context.user() {
+            tracing::info!(user_uid = %user_uid, ip = ?context.ip_address(), "User logged out");
+        }
+        context.clear_user();
+        context.clear();
+        Ok(())
+    }
+}
diff --git a/lib/service/auth/me.rs b/lib/service/auth/me.rs
new file mode 100644
index 0000000..55e3beb
--- /dev/null
+++ b/lib/service/auth/me.rs
@@ -0,0 +1,41 @@
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct ContextMe {
+    pub id: uuid::Uuid,
+    pub username: String,
+    pub display_name: Option<String>,
+    pub avatar_url: Option<String>,
+    pub has_unread_notifications: u64,
+    pub language: String,
+    pub timezone: String,
+}
+
+impl AppService {
+    pub async fn auth_me(&self, ctx: Session) -> Result<ContextMe, AppError> {
+        let user_id = ctx.user().ok_or(AppError::Unauthorized)?;
+        let user = self.auth_find_user_by_uid(user_id).await?;
+        let unread = self.unread_notifications_count(user_id).await.unwrap_or(0);
+
+        Ok(ContextMe {
+            id: user.id,
+            username: user.username,
+            display_name: if user.display_name.is_empty() {
+                None
+            } else {
+                Some(user.display_name)
+            },
+            avatar_url: if user.avatar_url.is_empty() {
+                None
+            } else {
+                Some(user.avatar_url)
+            },
+            has_unread_notifications: unread as u64,
+            language: "en".to_string(),
+            timezone: "UTC".to_string(),
+        })
+    }
+}
diff --git a/lib/service/auth/mod.rs b/lib/service/auth/mod.rs
new file mode 100644
index 0000000..f35e534
--- /dev/null
+++ b/lib/service/auth/mod.rs
@@ -0,0 +1,9 @@
+pub mod captcha;
+pub mod email;
+pub mod login;
+pub mod logout;
+pub mod me;
+pub mod register;
+pub mod reset_pass;
+pub mod rsa;
+pub mod totp;
diff --git a/lib/service/auth/register.rs b/lib/service/auth/register.rs
new file mode 100644
index 0000000..e24d7bb
--- /dev/null
+++ b/lib/service/auth/register.rs
@@ -0,0 +1,92 @@
+use argon2::{Argon2, password_hash::PasswordHasher};
+use db::sqlx;
+use model::users::UserModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct RegisterParams {
+    pub username: String,
+    pub email: String,
+    pub password: String,
+    pub captcha: String,
+}
+
+impl AppService {
+    pub async fn auth_register(
+        &self,
+        params: RegisterParams,
+        context: &Session,
+    ) -> Result<UserModel, AppError> {
+        self.auth_check_captcha(context, params.captcha).await?;
+        let password = self.auth_rsa_decode(context, params.password).await?;
+        Self::validate_password_strength(&password)?;
+
+        let username_exists = self
+            .auth_find_user_by_username(&params.username)
+            .await
+            .is_ok();
+        let email_exists =
+            self.auth_find_user_by_email(&params.email).await.is_ok();
+        if username_exists || email_exists {
+            return Err(AppError::AccountAlreadyExists);
+        }
+
+        let user_id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+        let password_hash = Argon2::default()
+            .hash_password(password.as_bytes())
+            .map_err(|e| AppError::PasswordHashError(e.to_string()))?
+            .to_string();
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let user = sqlx::query_as::<_, UserModel>(
+            "INSERT INTO \"user\" \
+             (id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+              last_sign_in_at, created_at, updated_at) \
+             VALUES ($1, $2, $3, '', '', true, true, NULL, $4, $4) \
+             RETURNING id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+                       last_sign_in_at, created_at, updated_at",
+        )
+        .bind(user_id)
+        .bind(&params.username)
+        .bind(&params.username)
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO user_email (\"user\", email, created_at, active, last_use_login, updated_at) \
+             VALUES ($1, $2, $3, true, NULL, $3)",
+        )
+        .bind(user_id)
+        .bind(&params.email)
+        .bind(now)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO user_password (\"user\", hash, salt, is_active, reason, created_at, updated_at) \
+             VALUES ($1, $2, '', true, NULL, $3, $3)",
+        )
+        .bind(user_id)
+        .bind(&password_hash)
+        .bind(now)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+
+        context.set_user(user_id);
+        context.remove(Self::RSA_PRIVATE_KEY);
+        context.remove(Self::RSA_PUBLIC_KEY);
+        tracing::info!(user_uid = %user_id, username = %user.username, "User registered successfully");
+        Ok(user)
+    }
+}
diff --git a/lib/service/auth/reset_pass.rs b/lib/service/auth/reset_pass.rs
new file mode 100644
index 0000000..9fc7e49
--- /dev/null
+++ b/lib/service/auth/reset_pass.rs
@@ -0,0 +1,153 @@
+use argon2::{Argon2, PasswordHasher};
+use chrono::{Duration, Utc};
+use db::sqlx;
+use email::EmailMessage;
+use rand::{RngExt, distr::Alphanumeric};
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Deserialize, Serialize, utoipa::ToSchema)]
+pub struct ResetPasswordRequest {
+    pub email: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, utoipa::ToSchema)]
+pub struct ResetPasswordVerifyParams {
+    pub token: String,
+    pub password: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct PendingResetPassword {
+    user_uid: uuid::Uuid,
+    created_at: chrono::DateTime<Utc>,
+}
+
+impl AppService {
+    const RESET_PASS_PREFIX: &'static str = "auth:reset_pass:";
+    const RESET_PASS_EXPIRY_HOURS: i64 = 1;
+    pub async fn auth_reset_password_request(
+        &self,
+        params: ResetPasswordRequest,
+    ) -> Result<(), AppError> {
+        let user = self.auth_find_user_by_email(&params.email).await.ok();
+
+        if let Some(user) = user {
+            let token = Self::generate_reset_token();
+            let cache_key = format!("{}{}", Self::RESET_PASS_PREFIX, token);
+            let now = chrono::Utc::now();
+
+            if let Err(e) = self
+                .cache
+                .set(
+                    &cache_key,
+                    &PendingResetPassword {
+                        user_uid: user.id,
+                        created_at: now,
+                    },
+                )
+                .await
+            {
+                tracing::error!(error = %e, user_uid = %user.id, "Failed to cache reset token");
+                return Ok(());
+            }
+
+            let domain = match self.config.main_domain() {
+                Ok(d) => d,
+                Err(e) => {
+                    tracing::error!(error = %e, "Domain not configured for password reset");
+                    return Ok(());
+                }
+            };
+            let reset_link =
+                format!("{}/auth/reset-password?token={}", domain, token);
+
+            if let Err(e) = self
+                .email
+                .send(EmailMessage {
+                    to: params.email.clone(),
+                    subject: "Reset Your Password".to_string(),
+                    body: format!(
+                        "You requested to reset your GitDataAI password.\n\n\
+                         Reset your password here:\n\n{}\n\n\
+                         If you did not request this, ignore this email.",
+                        reset_link
+                    ),
+                })
+                .await
+            {
+                tracing::error!(error = %e, email = %params.email, "Failed to queue password reset email");
+            }
+
+            tracing::info!(email = %params.email, user_uid = %user.id, "Password reset email queued");
+        }
+
+        Ok(())
+    }
+
+    pub async fn auth_reset_password_verify(
+        &self,
+        context: &Session,
+        params: ResetPasswordVerifyParams,
+    ) -> Result<(), AppError> {
+        if params.token.is_empty() {
+            return Err(AppError::InvalidResetToken);
+        }
+
+        let cache_key = format!("{}{}", Self::RESET_PASS_PREFIX, params.token);
+        let pending = self
+            .cache
+            .get::<PendingResetPassword>(&cache_key)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?
+            .ok_or(AppError::InvalidResetToken)?;
+
+        if Utc::now() - pending.created_at
+            > Duration::hours(Self::RESET_PASS_EXPIRY_HOURS)
+        {
+            let _ = self.cache.remove(&cache_key).await;
+            return Err(AppError::ResetTokenExpired);
+        }
+
+        self.cache
+            .remove(&cache_key)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let password = self.auth_rsa_decode(context, params.password).await?;
+        Self::validate_password_strength(&password)?;
+
+        let password_hash = Argon2::default()
+            .hash_password(password.as_bytes())
+            .map_err(|e| AppError::PasswordHashError(e.to_string()))?
+            .to_string();
+
+        let now = chrono::Utc::now();
+        let result = sqlx::query(
+            "UPDATE user_password SET hash = $1, updated_at = $2 WHERE \"user\" = $3 AND is_active = true",
+        )
+        .bind(&password_hash)
+        .bind(now)
+        .bind(pending.user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if result.rows_affected() == 0 {
+            return Err(AppError::InvalidResetToken);
+        }
+
+        tracing::info!(user_uid = %pending.user_uid, "Password reset successfully");
+        Ok(())
+    }
+
+    fn generate_reset_token() -> String {
+        #[allow(deprecated)]
+        let mut rng = rand::rng();
+        let token: String =
+            (0..64).map(|_| rng.sample(Alphanumeric) as char).collect();
+        format!("rst_{}", token)
+    }
+}
diff --git a/lib/service/auth/rsa.rs b/lib/service/auth/rsa.rs
new file mode 100644
index 0000000..7398e04
--- /dev/null
+++ b/lib/service/auth/rsa.rs
@@ -0,0 +1,150 @@
+use base64::Engine;
+use chacha20poly1305::{ChaCha20Poly1305, KeyInit, Nonce, aead::Aead};
+use hkdf::Hkdf;
+use rand_chacha::{ChaCha12Rng, rand_core::SeedableRng};
+use rsa::{
+    Pkcs1v15Encrypt, RsaPrivateKey, RsaPublicKey,
+    pkcs1::{DecodeRsaPrivateKey, EncodeRsaPrivateKey, EncodeRsaPublicKey},
+};
+use serde::{Deserialize, Serialize};
+use session::Session;
+use sha2::Sha256;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct RsaResponse {
+    pub public_key: String,
+}
+
+impl AppService {
+    pub const RSA_PRIVATE_KEY: &'static str = "rsa:private";
+    pub const RSA_PUBLIC_KEY: &'static str = "rsa:public";
+    const RSA_BIT_SIZE: usize = 2048;
+
+    fn derive_rsa_encryption_key(&self) -> [u8; 32] {
+        let secret = self
+            .config
+            .env
+            .get("APP_SESSION_SECRET")
+            .map(|s| s.as_str())
+            .expect("APP_SESSION_SECRET must be set in production. Do not use fallback keys.");
+        let hk = Hkdf::<Sha256>::new(
+            Some(b"rsa-session-encryption"),
+            secret.as_bytes(),
+        );
+        let mut okm = [0u8; 32];
+        hk.expand(b"rsa-private-key-aead", &mut okm)
+            .expect("HKDF expand within hash length");
+        okm
+    }
+
+    fn encrypt_rsa_key(&self, plaintext: &str) -> Result<String, AppError> {
+        let key = self.derive_rsa_encryption_key();
+        let cipher = ChaCha20Poly1305::new_from_slice(&key)
+            .expect("32-byte key is valid for ChaCha20Poly1305");
+        let nonce_bytes: [u8; 12] = rand::random();
+        let nonce = Nonce::from(nonce_bytes);
+        let ciphertext = cipher
+            .encrypt(&nonce, plaintext.as_bytes())
+            .map_err(|_| AppError::RsaGenerationError)?;
+        let mut combined = nonce_bytes.to_vec();
+        combined.extend_from_slice(&ciphertext);
+        Ok(base64::engine::general_purpose::STANDARD.encode(&combined))
+    }
+
+    fn decrypt_rsa_key(&self, encrypted: &str) -> Result<String, AppError> {
+        let key = self.derive_rsa_encryption_key();
+        let cipher = ChaCha20Poly1305::new_from_slice(&key)
+            .expect("32-byte key is valid for ChaCha20Poly1305");
+        let combined = base64::engine::general_purpose::STANDARD
+            .decode(encrypted)
+            .map_err(|_| AppError::RsaDecodeError)?;
+        if combined.len() < 12 {
+            return Err(AppError::RsaDecodeError);
+        }
+        let mut nonce_bytes = [0u8; 12];
+        nonce_bytes.copy_from_slice(&combined[..12]);
+        let nonce = Nonce::from(nonce_bytes);
+        let plaintext = cipher
+            .decrypt(&nonce, &combined[12..])
+            .map_err(|_| AppError::RsaDecodeError)?;
+        Ok(String::from_utf8(plaintext)
+            .map_err(|_| AppError::RsaDecodeError)?)
+    }
+
+    pub async fn auth_rsa(
+        &self,
+        context: &Session,
+    ) -> Result<RsaResponse, AppError> {
+        if context
+            .get::<String>(Self::RSA_PRIVATE_KEY)
+            .ok()
+            .flatten()
+            .is_some()
+            && context
+                .get::<String>(Self::RSA_PUBLIC_KEY)
+                .ok()
+                .flatten()
+                .is_some()
+        {
+            let public_key = context
+                .get::<String>(Self::RSA_PUBLIC_KEY)
+                .ok()
+                .flatten()
+                .expect("checked above");
+            return Ok(RsaResponse { public_key });
+        }
+
+        let seed: [u8; 32] = rand::random();
+        let mut rng = ChaCha12Rng::from_seed(seed);
+        let priv_key = RsaPrivateKey::new(&mut rng, Self::RSA_BIT_SIZE)
+            .map_err(|_| {
+                tracing::error!("RSA key generation failed");
+                AppError::RsaGenerationError
+            })?;
+        let pub_key = RsaPublicKey::from(&priv_key);
+        let priv_pem = priv_key
+            .to_pkcs1_pem(Default::default())
+            .map_err(|_| AppError::RsaGenerationError)?
+            .to_string();
+        let public_key = pub_key
+            .to_pkcs1_pem(Default::default())
+            .map_err(|_| AppError::RsaGenerationError)?
+            .to_string();
+
+        context
+            .insert(Self::RSA_PRIVATE_KEY, self.encrypt_rsa_key(&priv_pem)?)
+            .map_err(|_| AppError::RsaGenerationError)?;
+        context
+            .insert(Self::RSA_PUBLIC_KEY, public_key.clone())
+            .map_err(|_| AppError::RsaGenerationError)?;
+
+        Ok(RsaResponse { public_key })
+    }
+
+    pub async fn auth_rsa_decode(
+        &self,
+        context: &Session,
+        data: String,
+    ) -> Result<String, AppError> {
+        let encrypted_priv = context
+            .get::<String>(Self::RSA_PRIVATE_KEY)
+            .map_err(|_| AppError::RsaDecodeError)?
+            .ok_or(AppError::RsaDecodeError)?;
+        let priv_pem = self.decrypt_rsa_key(&encrypted_priv)?;
+
+        let priv_key = RsaPrivateKey::from_pkcs1_pem(&priv_pem).map_err(|_| {
+            tracing::warn!(ip = ?context.ip_address(), "RSA decode failed: invalid private key");
+            AppError::RsaDecodeError
+        })?;
+        let cipher = base64::engine::general_purpose::STANDARD
+            .decode(&data)
+            .map_err(|_| AppError::RsaDecodeError)?;
+        let decrypted = priv_key.decrypt(Pkcs1v15Encrypt, &cipher).map_err(|_| {
+            tracing::warn!(ip = ?context.ip_address(), "RSA decrypt failed");
+            AppError::RsaDecodeError
+        })?;
+        Ok(String::from_utf8_lossy(&decrypted).to_string())
+    }
+}
diff --git a/lib/service/auth/totp.rs b/lib/service/auth/totp.rs
new file mode 100644
index 0000000..03bd0c4
--- /dev/null
+++ b/lib/service/auth/totp.rs
@@ -0,0 +1,430 @@
+use argon2::{Argon2, PasswordHash, password_hash::PasswordVerifier};
+use db::sqlx;
+use hmac::{Hmac, KeyInit, Mac};
+use model::users::{User2FaModel, user_pass::UserPasswordModel};
+use rand::RngExt;
+use serde::{Deserialize, Serialize};
+use session::Session;
+use sha1::Sha1;
+use sha2::{Digest, Sha256};
+use uuid::Uuid;
+
+use crate::{AppService, constant_time_eq, error::AppError};
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct Enable2FAResponse {
+    pub secret: String,
+    pub qr_code: String,
+    pub backup_codes: Vec<String>,
+}
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct Verify2FAParams {
+    pub code: String,
+}
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct Disable2FAParams {
+    pub code: String,
+    pub password: String,
+}
+
+#[derive(Deserialize, Serialize, Clone, Debug, utoipa::ToSchema)]
+pub struct Get2FAStatusResponse {
+    pub is_enabled: bool,
+    pub method: Option<String>,
+    pub has_backup_codes: bool,
+}
+impl AppService {
+    pub async fn auth_2fa_enable(
+        &self,
+        context: &Session,
+    ) -> Result<Enable2FAResponse, AppError> {
+        let user_uid = context.user().ok_or(AppError::Unauthorized)?;
+        let user = self.auth_find_user_by_uid(user_uid).await?;
+
+        let existing = self.find_2fa(user_uid).await?;
+        if existing.as_ref().is_some_and(|two_fa| two_fa.enabled) {
+            return Err(AppError::TwoFactorAlreadyEnabled);
+        }
+
+        let secret = self.generate_totp_secret();
+        let backup_codes = self.generate_backup_codes(10);
+        let qr_code = format!(
+            "otpauth://totp/GitDataAI:{}?secret={}&issuer=GitDataAI",
+            user.username, secret
+        );
+        let now = chrono::Utc::now();
+        let hashed_backup_codes =
+            Self::hash_backup_codes(&backup_codes).join(".");
+
+        if existing.is_some() {
+            sqlx::query(
+                "UPDATE user_2fa SET secret = $1, backup_codes = $2, enabled = false, updated_at = $3 \
+                 WHERE \"user\" = $4",
+            )
+            .bind(&secret)
+            .bind(&hashed_backup_codes)
+            .bind(now)
+            .bind(user_uid)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        } else {
+            sqlx::query(
+                "INSERT INTO user_2fa (\"user\", secret, backup_codes, enabled, created_at, updated_at) \
+                 VALUES ($1, $2, $3, false, $4, $4)",
+            )
+            .bind(user_uid)
+            .bind(&secret)
+            .bind(&hashed_backup_codes)
+            .bind(now)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        Ok(Enable2FAResponse {
+            secret,
+            qr_code,
+            backup_codes,
+        })
+    }
+
+    pub async fn auth_2fa_verify_and_enable(
+        &self,
+        context: &Session,
+        params: Verify2FAParams,
+    ) -> Result<(), AppError> {
+        let user_uid = context.user().ok_or(AppError::Unauthorized)?;
+        let two_fa = self
+            .find_2fa(user_uid)
+            .await?
+            .ok_or(AppError::TwoFactorNotSetup)?;
+        if two_fa.enabled {
+            return Err(AppError::TwoFactorAlreadyEnabled);
+        }
+        let secret =
+            two_fa.secret.as_ref().ok_or(AppError::TwoFactorNotSetup)?;
+        if !self.verify_totp_code(secret, &params.code)? {
+            return Err(AppError::InvalidTwoFactorCode);
+        }
+
+        sqlx::query("UPDATE user_2fa SET enabled = true, updated_at = $1 WHERE \"user\" = $2")
+            .bind(chrono::Utc::now())
+            .bind(user_uid)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+
+    pub async fn auth_2fa_disable(
+        &self,
+        context: &Session,
+        params: Disable2FAParams,
+    ) -> Result<(), AppError> {
+        let user_uid = context.user().ok_or(AppError::Unauthorized)?;
+        let password = self.auth_rsa_decode(context, params.password).await?;
+        self.verify_user_password(user_uid, &password).await?;
+
+        let two_fa = self
+            .find_2fa(user_uid)
+            .await?
+            .ok_or(AppError::TwoFactorNotSetup)?;
+        if !two_fa.enabled {
+            return Err(AppError::TwoFactorNotEnabled);
+        }
+        if !self
+            .verify_2fa_or_backup_code(&two_fa, &params.code)
+            .await?
+        {
+            return Err(AppError::InvalidTwoFactorCode);
+        }
+
+        sqlx::query("DELETE FROM user_2fa WHERE \"user\" = $1")
+            .bind(user_uid)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+
+    pub(crate) async fn auth_2fa_verify(
+        &self,
+        user_uid: Uuid,
+        code: &str,
+    ) -> Result<bool, AppError> {
+        let Some(two_fa) = self.find_2fa(user_uid).await? else {
+            return Ok(true);
+        };
+        if !two_fa.enabled {
+            return Ok(true);
+        }
+        self.verify_2fa_or_backup_code(&two_fa, code).await
+    }
+
+    pub(crate) async fn auth_2fa_status_by_uid(
+        &self,
+        user_uid: Uuid,
+    ) -> Result<Get2FAStatusResponse, AppError> {
+        let Some(two_fa) = self.find_2fa(user_uid).await? else {
+            return Ok(Get2FAStatusResponse {
+                is_enabled: false,
+                method: None,
+                has_backup_codes: false,
+            });
+        };
+        Ok(Get2FAStatusResponse {
+            is_enabled: two_fa.enabled,
+            method: Some("totp".to_string()),
+            has_backup_codes: !two_fa.backup_codes.is_empty(),
+        })
+    }
+
+    pub async fn auth_2fa_status(
+        &self,
+        context: &Session,
+    ) -> Result<Get2FAStatusResponse, AppError> {
+        let user_uid = context.user().ok_or(AppError::Unauthorized)?;
+        self.auth_2fa_status_by_uid(user_uid).await
+    }
+
+    pub async fn auth_2fa_verify_login(
+        &self,
+        context: &Session,
+        code: &str,
+    ) -> Result<bool, AppError> {
+        let Some(totp_key) =
+            context.get::<String>(Self::TOTP_KEY).ok().flatten()
+        else {
+            return Ok(false);
+        };
+        let Some(user_uid) = self
+            .cache
+            .get::<Uuid>(&totp_key)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?
+        else {
+            return Ok(false);
+        };
+        let verified = self.auth_2fa_verify(user_uid, code).await?;
+        if verified {
+            context.remove(Self::TOTP_KEY);
+            let _ = self.cache.remove(&totp_key).await;
+            context.set_user(user_uid);
+        }
+        Ok(verified)
+    }
+
+    pub async fn auth_2fa_regenerate_backup_codes(
+        &self,
+        context: &Session,
+        password: String,
+    ) -> Result<Vec<String>, AppError> {
+        let user_uid = context.user().ok_or(AppError::Unauthorized)?;
+        let password = self.auth_rsa_decode(context, password).await?;
+        self.verify_user_password(user_uid, &password).await?;
+        let two_fa = self
+            .find_2fa(user_uid)
+            .await?
+            .ok_or(AppError::TwoFactorNotSetup)?;
+        if !two_fa.enabled {
+            return Err(AppError::TwoFactorNotEnabled);
+        }
+
+        let backup_codes = self.generate_backup_codes(10);
+        sqlx::query("UPDATE user_2fa SET backup_codes = $1, updated_at = $2 WHERE \"user\" = $3")
+            .bind(Self::hash_backup_codes(&backup_codes).join("."))
+            .bind(chrono::Utc::now())
+            .bind(user_uid)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(backup_codes)
+    }
+    fn generate_totp_secret(&self) -> String {
+        const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+        #[allow(deprecated)]
+        let mut rng = rand::rng();
+        (0..32)
+            .map(|_| {
+                #[allow(deprecated)]
+                let idx = rng.random_range(0..CHARSET.len());
+                CHARSET[idx] as char
+            })
+            .collect()
+    }
+
+    fn generate_backup_codes(&self, count: usize) -> Vec<String> {
+        #[allow(deprecated)]
+        let mut rng = rand::rng();
+        (0..count)
+            .map(|_| {
+                format!(
+                    "{:04}-{:04}-{:04}",
+                    rng.random_range(0..10000),
+                    rng.random_range(0..10000),
+                    rng.random_range(0..10000)
+                )
+            })
+            .collect()
+    }
+
+    fn hash_backup_code(code: &str) -> String {
+        let mut hasher = Sha256::new();
+        hasher.update(code.as_bytes());
+        hasher
+            .finalize()
+            .iter()
+            .map(|b| format!("{:02x}", b))
+            .collect::<String>()
+    }
+
+    fn hash_backup_codes(codes: &[String]) -> Vec<String> {
+        codes.iter().map(|c| Self::hash_backup_code(c)).collect()
+    }
+
+    fn verify_totp_code(
+        &self,
+        secret: &str,
+        code: &str,
+    ) -> Result<bool, AppError> {
+        let now = chrono::Utc::now().timestamp() as u64;
+        let time_step = 30;
+        let counter = now / time_step;
+
+        for offset in [-1i64, 0, 1] {
+            let test_counter = (counter as i64 + offset) as u64;
+            let expected_code =
+                self.generate_totp_code(secret, test_counter)?;
+            if constant_time_eq(&expected_code, code) {
+                return Ok(true);
+            }
+        }
+
+        Ok(false)
+    }
+
+    fn generate_totp_code(
+        &self,
+        secret: &str,
+        counter: u64,
+    ) -> Result<String, AppError> {
+        let secret_bytes = self.decode_base32(secret)?;
+
+        let counter_bytes = counter.to_be_bytes();
+
+        let mut mac = Hmac::<Sha1>::new_from_slice(&secret_bytes)
+            .map_err(|_| AppError::InvalidTwoFactorCode)?;
+        mac.update(&counter_bytes);
+        let result = mac.finalize().into_bytes();
+
+        let offset = (result[19] & 0x0f) as usize;
+        let code = u32::from_be_bytes([
+            result[offset] & 0x7f,
+            result[offset + 1],
+            result[offset + 2],
+            result[offset + 3],
+        ]);
+
+        Ok(format!("{:06}", code % 1_000_000))
+    }
+
+    fn decode_base32(&self, input: &str) -> Result<Vec<u8>, AppError> {
+        const CHARSET: &str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+        let input = input.to_uppercase().replace("=", "");
+        let mut bits = 0u64;
+        let mut bit_count = 0;
+        let mut output = Vec::new();
+
+        for c in input.chars() {
+            let val =
+                CHARSET.find(c).ok_or(AppError::InvalidTwoFactorCode)? as u64;
+            bits = (bits << 5) | val;
+            bit_count += 5;
+
+            if bit_count >= 8 {
+                bit_count -= 8;
+                output.push((bits >> bit_count) as u8);
+                bits &= (1 << bit_count) - 1;
+            }
+        }
+
+        Ok(output)
+    }
+
+    async fn verify_user_password(
+        &self,
+        user_uid: Uuid,
+        password: &str,
+    ) -> Result<(), AppError> {
+        let user_password = sqlx::query_as::<_, UserPasswordModel>(
+            "SELECT \"user\", hash, salt, is_active, reason, created_at, updated_at \
+             FROM user_password WHERE \"user\" = $1 AND is_active = true",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        let password_hash = PasswordHash::new(&user_password.hash)
+            .map_err(|_| AppError::InvalidPassword)?;
+
+        Argon2::default()
+            .verify_password(password.as_bytes(), &password_hash)
+            .map_err(|_| AppError::InvalidPassword)?;
+
+        Ok(())
+    }
+
+    async fn find_2fa(
+        &self,
+        user_uid: Uuid,
+    ) -> Result<Option<User2FaModel>, AppError> {
+        sqlx::query_as::<_, User2FaModel>(
+            "SELECT \"user\", secret, backup_codes, enabled, created_at, updated_at \
+             FROM user_2fa WHERE \"user\" = $1",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))
+    }
+
+    async fn verify_2fa_or_backup_code(
+        &self,
+        two_fa: &User2FaModel,
+        code: &str,
+    ) -> Result<bool, AppError> {
+        let secret =
+            two_fa.secret.as_ref().ok_or(AppError::TwoFactorNotSetup)?;
+        if self.verify_totp_code(secret, code)? {
+            return Ok(true);
+        }
+
+        let hashed_code = Self::hash_backup_code(code);
+        let mut backup_codes: Vec<String> = two_fa
+            .backup_codes
+            .split('.')
+            .filter(|code| !code.is_empty())
+            .map(ToOwned::to_owned)
+            .collect();
+        if backup_codes.contains(&hashed_code) {
+            backup_codes.retain(|stored| stored != &hashed_code);
+            sqlx::query(
+                "UPDATE user_2fa SET backup_codes = $1, updated_at = $2 WHERE \"user\" = $3",
+            )
+            .bind(backup_codes.join("."))
+            .bind(chrono::Utc::now())
+            .bind(two_fa.user)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+            return Ok(true);
+        }
+
+        Ok(false)
+    }
+}
diff --git a/lib/service/error.rs b/lib/service/error.rs
new file mode 100644
index 0000000..e7f3a6a
--- /dev/null
+++ b/lib/service/error.rs
@@ -0,0 +1,145 @@
+use std::fmt;
+
+#[derive(Debug)]
+pub enum AppError {
+    UserNotFound,
+    RsaGenerationError,
+    RsaDecodeError,
+    CaptchaError,
+    TwoFactorRequired,
+    Unauthorized,
+    DoMainNotSet,
+    UserNameExists,
+    EmailExists,
+    AccountAlreadyExists,
+    TxnError,
+    PasswordHashError(String),
+    TwoFactorAlreadyEnabled,
+    TwoFactorNotSetup,
+    InvalidTwoFactorCode,
+    TwoFactorNotEnabled,
+    DatabaseError(String),
+    InvalidPassword,
+    PasswordTooWeak,
+    ProjectNotFound,
+    NoPower,
+    InternalError,
+    NotFound(String),
+    RoleParseError,
+    ProjectNameAlreadyExists,
+    RepoNameAlreadyExists,
+    AvatarUploadError(String),
+    InternalServerError(String),
+    PermissionDenied,
+    RepoNotFound,
+    RepoForBidAccess,
+    SerdeError(serde_json::Error),
+    Io(std::io::Error),
+    BadRequest(String),
+    Forbidden(String),
+    Conflict(String),
+    InvalidResetToken,
+    ResetTokenExpired,
+    ResetTokenUsed,
+    IssueNotFound,
+    LabelNotFound,
+    MilestoneNotFound,
+    PullRequestNotFound,
+    CommentNotFound,
+    GitRpcError(String),
+    AiError(ai::error::AiError),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AppError::UserNotFound => write!(f, "user not found"),
+            AppError::RsaGenerationError => {
+                write!(f, "RSA key generation failed")
+            }
+            AppError::RsaDecodeError => write!(f, "RSA decode failed"),
+            AppError::CaptchaError => write!(f, "captcha verification failed"),
+            AppError::TwoFactorRequired => {
+                write!(f, "two-factor authentication required")
+            }
+            AppError::Unauthorized => write!(f, "unauthorized"),
+            AppError::DoMainNotSet => write!(f, "domain not configured"),
+            AppError::UserNameExists => write!(f, "username already exists"),
+            AppError::EmailExists => write!(f, "email already exists"),
+            AppError::AccountAlreadyExists => {
+                write!(f, "account already exists")
+            }
+            AppError::TxnError => write!(f, "transaction error"),
+            AppError::PasswordHashError(e) => {
+                write!(f, "password hash error: {}", e)
+            }
+            AppError::TwoFactorAlreadyEnabled => {
+                write!(f, "two-factor already enabled")
+            }
+            AppError::TwoFactorNotSetup => write!(f, "two-factor not setup"),
+            AppError::InvalidTwoFactorCode => {
+                write!(f, "invalid two-factor code")
+            }
+            AppError::TwoFactorNotEnabled => {
+                write!(f, "two-factor not enabled")
+            }
+            AppError::DatabaseError(e) => write!(f, "database error: {}", e),
+            AppError::InvalidPassword => write!(f, "invalid password"),
+            AppError::PasswordTooWeak => write!(f, "password too weak"),
+            AppError::ProjectNotFound => write!(f, "project not found"),
+            AppError::NoPower => write!(f, "permission denied"),
+            AppError::InternalError => write!(f, "internal error"),
+            AppError::NotFound(msg) => write!(f, "not found: {}", msg),
+            AppError::RoleParseError => write!(f, "role parse error"),
+            AppError::ProjectNameAlreadyExists => {
+                write!(f, "project name already exists")
+            }
+            AppError::RepoNameAlreadyExists => {
+                write!(f, "repo name already exists")
+            }
+            AppError::AvatarUploadError(e) => {
+                write!(f, "avatar upload error: {}", e)
+            }
+            AppError::InternalServerError(e) => {
+                write!(f, "internal server error: {}", e)
+            }
+            AppError::PermissionDenied => write!(f, "permission denied"),
+            AppError::RepoNotFound => write!(f, "repo not found"),
+            AppError::RepoForBidAccess => write!(f, "repo access forbidden"),
+            AppError::SerdeError(e) => write!(f, "serde error: {}", e),
+            AppError::Io(e) => write!(f, "IO error: {}", e),
+            AppError::BadRequest(msg) => write!(f, "bad request: {}", msg),
+            AppError::Forbidden(msg) => write!(f, "forbidden: {}", msg),
+            AppError::Conflict(msg) => write!(f, "conflict: {}", msg),
+            AppError::InvalidResetToken => write!(f, "invalid reset token"),
+            AppError::ResetTokenExpired => write!(f, "reset token expired"),
+            AppError::ResetTokenUsed => write!(f, "reset token already used"),
+            AppError::IssueNotFound => write!(f, "issue not found"),
+            AppError::LabelNotFound => write!(f, "label not found"),
+            AppError::MilestoneNotFound => write!(f, "milestone not found"),
+            AppError::PullRequestNotFound => {
+                write!(f, "pull request not found")
+            }
+            AppError::CommentNotFound => write!(f, "comment not found"),
+            AppError::GitRpcError(e) => write!(f, "git rpc error: {}", e),
+            AppError::AiError(e) => write!(f, "ai error: {}", e),
+        }
+    }
+}
+
+impl std::error::Error for AppError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            AppError::SerdeError(e) => Some(e),
+            AppError::Io(e) => Some(e),
+            AppError::AiError(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl From<ai::error::AiError> for AppError {
+    fn from(e: ai::error::AiError) -> Self {
+        AppError::AiError(e)
+    }
+}
diff --git a/lib/service/git/archive.rs b/lib/service/git/archive.rs
new file mode 100644
index 0000000..5e78d11
--- /dev/null
+++ b/lib/service/git/archive.rs
@@ -0,0 +1,48 @@
+use git::rpc::{
+    proto as p, proto::archive_service_client::ArchiveServiceClient,
+};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_archive_tar(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        options: Option<p::ArchiveOptions>,
+    ) -> Result<p::ArchiveTarResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = ArchiveServiceClient::new(self.git.clone());
+        let resp = client
+            .archive_tar(tonic::Request::new(p::ArchiveTarRequest {
+                repo_id: repo.id.to_string(),
+                options,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_archive_zip(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        options: Option<p::ArchiveOptions>,
+    ) -> Result<p::ArchiveZipResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = ArchiveServiceClient::new(self.git.clone());
+        let resp = client
+            .archive_zip(tonic::Request::new(p::ArchiveZipRequest {
+                repo_id: repo.id.to_string(),
+                options,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/blame.rs b/lib/service/git/blame.rs
new file mode 100644
index 0000000..1cfd6da
--- /dev/null
+++ b/lib/service/git/blame.rs
@@ -0,0 +1,82 @@
+use git::rpc::{proto as p, proto::blame_service_client::BlameServiceClient};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_blame_file(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        path: String,
+        rev: Option<String>,
+        options: Option<p::BlameOptions>,
+    ) -> Result<p::BlameFileResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlameServiceClient::new(self.git.clone());
+        let resp = client
+            .blame_file(tonic::Request::new(p::BlameFileRequest {
+                repo_id: repo.id.to_string(),
+                path,
+                rev,
+                options,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_blame_hunk(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        path: String,
+        rev: Option<String>,
+        start_line: u32,
+        end_line: u32,
+    ) -> Result<p::BlameHunkResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlameServiceClient::new(self.git.clone());
+        let resp = client
+            .blame_hunk(tonic::Request::new(p::BlameHunkRequest {
+                repo_id: repo.id.to_string(),
+                path,
+                rev,
+                start_line,
+                end_line,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_blame_lines(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        path: String,
+        rev: Option<String>,
+        start_line: u32,
+        end_line: u32,
+    ) -> Result<p::BlameLinesResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlameServiceClient::new(self.git.clone());
+        let resp = client
+            .blame_lines(tonic::Request::new(p::BlameLinesRequest {
+                repo_id: repo.id.to_string(),
+                path,
+                rev,
+                start_line,
+                end_line,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/blob.rs b/lib/service/git/blob.rs
new file mode 100644
index 0000000..06c7880
--- /dev/null
+++ b/lib/service/git/blob.rs
@@ -0,0 +1,113 @@
+use git::rpc::{proto as p, proto::blob_service_client::BlobServiceClient};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_blob_load(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+        path: String,
+    ) -> Result<p::BlobLoadResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlobServiceClient::new(self.git.clone());
+        let resp = client
+            .blob_load(tonic::Request::new(p::BlobLoadRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(p::ObjectId { value: oid }),
+                path,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_blob_size(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+        path: String,
+    ) -> Result<p::BlobSizeResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlobServiceClient::new(self.git.clone());
+        let resp = client
+            .blob_size(tonic::Request::new(p::BlobSizeRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(p::ObjectId { value: oid }),
+                path,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_blob_exists(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+    ) -> Result<p::BlobExistsResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlobServiceClient::new(self.git.clone());
+        let resp = client
+            .blob_exists(tonic::Request::new(p::BlobExistsRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(p::ObjectId { value: oid }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_blob_is_binary(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+    ) -> Result<p::BlobIsBinaryResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BlobServiceClient::new(self.git.clone());
+        let resp = client
+            .blob_is_binary(tonic::Request::new(p::BlobIsBinaryRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(p::ObjectId { value: oid }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_blob_upload(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        path: String,
+        blob: Vec<u8>,
+    ) -> Result<p::BlobUploadResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = BlobServiceClient::new(self.git.clone());
+        let resp = client
+            .blob_upload(tonic::Request::new(p::BlobUploadRequest {
+                repo_id: repo.id.to_string(),
+                blob,
+                path,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/branch.rs b/lib/service/git/branch.rs
new file mode 100644
index 0000000..ec97703
--- /dev/null
+++ b/lib/service/git/branch.rs
@@ -0,0 +1,196 @@
+use git::rpc::{proto as p, proto::branch_service_client::BranchServiceClient};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_branch_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        pagination: Pagination,
+    ) -> Result<p::BranchListResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let mut resp = client
+            .branch_list(tonic::Request::new(p::BranchListRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let offset = pagination.offset() as usize;
+        let limit = pagination.limit() as usize;
+        if offset > 0 || resp.branches.len() > limit {
+            let start = offset.min(resp.branches.len());
+            let end = (start + limit).min(resp.branches.len());
+            resp.branches = resp.branches.drain(start..end).collect();
+        }
+        Ok(resp)
+    }
+
+    pub async fn git_branch_info(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        branch: String,
+    ) -> Result<p::BranchInfoResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_info(tonic::Request::new(p::BranchInfoRequest {
+                repo_id: repo.id.to_string(),
+                branch,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_branch_summary(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<p::BranchSummaryResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_summary(tonic::Request::new(p::BranchSummaryRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_branch_head(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<p::BranchHeadResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_head(tonic::Request::new(p::BranchHeadRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_branch_ahead_behind(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        local_branch: String,
+        remote_branch: String,
+    ) -> Result<p::BranchAheadBehindResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_ahead_behind(tonic::Request::new(
+                p::BranchAheadBehindRequest {
+                    repo_id: repo.id.to_string(),
+                    local_branch,
+                    remote_branch,
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_branch_upstream(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        branch: String,
+    ) -> Result<p::BranchUpstreamResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_upstream(tonic::Request::new(p::BranchUpstreamRequest {
+                repo_id: repo.id.to_string(),
+                branch,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_branch_fork(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::BranchForkParams,
+    ) -> Result<p::BranchForkResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_fork(tonic::Request::new(p::BranchForkRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+
+    pub async fn git_branch_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::BranchDeleteParams,
+    ) -> Result<p::BranchDeleteResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_delete(tonic::Request::new(p::BranchDeleteRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+
+    pub async fn git_branch_rename(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::BranchReNameParams,
+    ) -> Result<p::BranchRenameResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_rename(tonic::Request::new(p::BranchRenameRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/commit.rs b/lib/service/git/commit.rs
new file mode 100644
index 0000000..5b82c19
--- /dev/null
+++ b/lib/service/git/commit.rs
@@ -0,0 +1,192 @@
+use git::rpc::{proto as p, proto::commit_service_client::CommitServiceClient};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_commit_info(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+    ) -> Result<p::CommitInfoResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_info(tonic::Request::new(p::CommitInfoRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: oid }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_commit_history(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        limit: u64,
+        skip: u64,
+        sort: i32,
+        branch: Option<String>,
+    ) -> Result<p::CommitHistoryResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_history(tonic::Request::new(p::CommitHistoryRequest {
+                repo_id: repo.id.to_string(),
+                limit,
+                skip,
+                sort,
+                branch,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_commit_summary(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<p::CommitSummaryResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_summary(tonic::Request::new(p::CommitSummaryRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_commit_walk(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::CommitWalkParams,
+    ) -> Result<p::CommitWalkResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_walk(tonic::Request::new(p::CommitWalkRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_commit_refs(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<p::CommitRefsResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_refs(tonic::Request::new(p::CommitRefsRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_commit_prefix(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        prefix: String,
+    ) -> Result<p::CommitPrefixResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_prefix(tonic::Request::new(p::CommitPrefixRequest {
+                repo_id: repo.id.to_string(),
+                prefix,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_commit_exists(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+    ) -> Result<p::CommitExistsResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .commit_exists(tonic::Request::new(p::CommitExistsRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: oid }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_cherry_pick(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::CommitCherryPickParams,
+    ) -> Result<p::CherryPickResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .cherry_pick(tonic::Request::new(p::CherryPickRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+
+    pub async fn git_cherry_pick_sequence(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::CommitCherryPickSequence,
+    ) -> Result<p::CherryPickSequenceResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .cherry_pick_sequence(tonic::Request::new(
+                p::CherryPickSequenceRequest {
+                    repo_id: repo.id.to_string(),
+                    params: Some(params),
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/commit_status.rs b/lib/service/git/commit_status.rs
new file mode 100644
index 0000000..36f38e6
--- /dev/null
+++ b/lib/service/git/commit_status.rs
@@ -0,0 +1,151 @@
+use chrono::Utc;
+use db::sqlx;
+use model::repos::RepoCommitStatusModel;
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct CommitStatusResponse {
+    pub id: Uuid,
+    pub commit_sha: String,
+    pub state: String,
+    pub target_url: Option<String>,
+    pub description: Option<String>,
+    pub context: String,
+    pub creator: Uuid,
+    pub created_at: chrono::DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct CombinedCommitStatus {
+    pub sha: String,
+    pub state: String,
+    pub total_count: i64,
+    pub statuses: Vec<CommitStatusResponse>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct CreateCommitStatus {
+    pub state: String,
+    pub target_url: Option<String>,
+    pub description: Option<String>,
+    pub context: Option<String>,
+}
+
+impl AppService {
+    pub async fn git_commit_status_list(
+        &self,
+        repo_id: Uuid,
+        commit_sha: &str,
+    ) -> Result<Vec<CommitStatusResponse>, AppError> {
+        let rows = sqlx::query_as::<_, RepoCommitStatusModel>(
+            "SELECT id, repo, commit_sha, state, target_url, description, \
+             context, creator, created_at, updated_at \
+             FROM repo_commit_status \
+             WHERE repo = $1 AND commit_sha = $2 \
+             ORDER BY created_at DESC",
+        )
+        .bind(repo_id)
+        .bind(commit_sha)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(status_to_response).collect())
+    }
+
+    pub async fn git_commit_status_combined(
+        &self,
+        repo_id: Uuid,
+        commit_sha: &str,
+    ) -> Result<CombinedCommitStatus, AppError> {
+        let statuses = self.git_commit_status_list(repo_id, commit_sha).await?;
+        let state = combined_state(&statuses);
+        Ok(CombinedCommitStatus {
+            sha: commit_sha.to_string(),
+            state,
+            total_count: statuses.len() as i64,
+            statuses,
+        })
+    }
+
+    pub async fn git_commit_status_create(
+        &self,
+        repo_id: Uuid,
+        user_id: Uuid,
+        commit_sha: &str,
+        params: CreateCommitStatus,
+    ) -> Result<CommitStatusResponse, AppError> {
+        if !["pending", "success", "failure", "error"].contains(&params.state.as_str()) {
+            return Err(AppError::BadRequest(
+                "state must be one of: pending, success, failure, error".to_string(),
+            ));
+        }
+
+        let id = Uuid::now_v7();
+        let now = Utc::now();
+        let context = params.context.unwrap_or_else(|| "default".to_string());
+
+        let row = sqlx::query_as::<_, RepoCommitStatusModel>(
+            "INSERT INTO repo_commit_status (id, repo, commit_sha, state, target_url, \
+             description, context, creator, created_at, updated_at) \
+             VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$9) RETURNING *",
+        )
+        .bind(id)
+        .bind(repo_id)
+        .bind(commit_sha)
+        .bind(&params.state)
+        .bind(&params.target_url)
+        .bind(&params.description)
+        .bind(&context)
+        .bind(user_id)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(status_to_response(row))
+    }
+}
+
+impl AppService {
+    pub async fn git_commit_status_list_by_name(&self, ctx: &Session, wk: &str, repo: &str, sha: &str) -> Result<Vec<CommitStatusResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_commit_status_list(repo.id, sha).await
+    }
+    pub async fn git_commit_status_combined_by_name(&self, ctx: &Session, wk: &str, repo: &str, sha: &str) -> Result<CombinedCommitStatus, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_commit_status_combined(repo.id, sha).await
+    }
+    pub async fn git_commit_status_create_by_name(&self, ctx: &Session, user_id: Uuid, wk: &str, repo: &str, sha: &str, params: CreateCommitStatus) -> Result<CommitStatusResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_commit_status_create(repo.id, user_id, sha, params).await
+    }
+}
+
+fn status_to_response(s: RepoCommitStatusModel) -> CommitStatusResponse {
+    CommitStatusResponse {
+        id: s.id,
+        commit_sha: s.commit_sha,
+        state: s.state,
+        target_url: s.target_url,
+        description: s.description,
+        context: s.context,
+        creator: s.creator,
+        created_at: s.created_at,
+    }
+}
+
+fn combined_state(statuses: &[CommitStatusResponse]) -> String {
+    if statuses.is_empty() {
+        return "pending".to_string();
+    }
+    let has = |s: &str| statuses.iter().any(|st| st.state == s);
+    (if has("error") { "error" }
+    else if has("failure") { "failure" }
+    else if has("pending") { "pending" }
+    else { "success" }).to_string()
+}
diff --git a/lib/service/git/compare.rs b/lib/service/git/compare.rs
new file mode 100644
index 0000000..aa4b8b1
--- /dev/null
+++ b/lib/service/git/compare.rs
@@ -0,0 +1,114 @@
+use git::rpc::{proto as p, proto::commit_service_client::CommitServiceClient};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct CompareResponse {
+    pub base_commit: CompareCommit,
+    pub head_commit: CompareCommit,
+    pub ahead_by: i32,
+    pub behind_by: i32,
+    pub total_commits: i32,
+    pub commits: Vec<CompareCommit>,
+    pub files_changed: u64,
+    pub insertions: u64,
+    pub deletions: u64,
+}
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct CompareCommit {
+    pub sha: String,
+    pub message: String,
+    pub author_name: Option<String>,
+    pub author_email: Option<String>,
+}
+
+impl AppService {
+    pub async fn git_compare(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        base: &str,
+        head: &str,
+    ) -> Result<CompareResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = CommitServiceClient::new(self.git.clone());
+
+        fn oid(s: &str) -> p::ObjectId {
+            p::ObjectId { value: s.to_string() }
+        }
+
+        let base_info = client
+            .commit_info(tonic::Request::new(p::CommitInfoRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(oid(base)),
+            }))
+            .await.map_err(rpc_err)?.into_inner();
+
+        let head_info = client
+            .commit_info(tonic::Request::new(p::CommitInfoRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(oid(head)),
+            }))
+            .await.map_err(rpc_err)?.into_inner();
+
+        let history = client
+            .commit_history(tonic::Request::new(p::CommitHistoryRequest {
+                repo_id: repo.id.to_string(),
+                limit: 250, skip: 0, sort: 0,
+                branch: Some(format!("{base}..{head}")),
+            }))
+            .await.map_err(rpc_err)?.into_inner();
+
+        let commits: Vec<CompareCommit> = history.commits.into_iter().map(|c| {
+            let author_name = c.author.as_ref().map(|a| a.name.clone());
+            let author_email = c.author.as_ref().map(|a| a.email.clone());
+            CompareCommit {
+                sha: c.oid.map(|o| o.value).unwrap_or_default(),
+                message: c.summary,
+                author_name,
+                author_email,
+            }
+        }).collect();
+
+        let diff = crate::AppService::git_diff_stats(
+            self, ctx, wk_name, repo_name,
+            base.to_string(), head.to_string(), None,
+        ).await?;
+
+        let stats = diff.result.and_then(|r| r.stats);
+        let files_changed = stats.as_ref().map(|s| s.files_changed).unwrap_or(0);
+        let insertions = stats.as_ref().map(|s| s.insertions).unwrap_or(0);
+        let deletions = stats.as_ref().map(|s| s.deletions).unwrap_or(0);
+
+        Ok(CompareResponse {
+            base_commit: cmt(base_info.commit),
+            head_commit: cmt(head_info.commit),
+            ahead_by: commits.len() as i32,
+            behind_by: 0,
+            total_commits: commits.len() as i32,
+            commits,
+            files_changed,
+            insertions,
+            deletions,
+        })
+    }
+}
+
+fn cmt(c: Option<p::CommitMeta>) -> CompareCommit {
+    c.map(|c| {
+        let author_name = c.author.as_ref().map(|a| a.name.clone());
+        let author_email = c.author.as_ref().map(|a| a.email.clone());
+        CompareCommit {
+            sha: c.oid.map(|o| o.value).unwrap_or_default(),
+            message: c.message,
+            author_name,
+            author_email,
+        }
+    }).unwrap_or_else(|| CompareCommit {
+        sha: String::new(), message: String::new(),
+        author_name: None, author_email: None,
+    })
+}
diff --git a/lib/service/git/contents.rs b/lib/service/git/contents.rs
new file mode 100644
index 0000000..552c248
--- /dev/null
+++ b/lib/service/git/contents.rs
@@ -0,0 +1,182 @@
+use db::sqlx;
+use git::rpc::{
+    proto as p,
+    proto::blob_service_client::BlobServiceClient,
+};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct ContentResponse {
+    pub path: String,
+    pub name: String,
+    #[serde(rename = "type")]
+    pub content_type: String,
+    pub size: i64,
+    pub encoding: Option<String>,
+    pub content: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct CreateContent {
+    pub message: String,
+    pub content: String,
+    pub branch: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct UpdateContent {
+    pub message: String,
+    pub content: String,
+    pub sha: String,
+    pub branch: Option<String>,
+}
+
+impl AppService {
+    pub async fn git_contents_get_by_name(&self, ctx: &Session, wk: &str, repo: &str, path: &str, ref_name: Option<&str>) -> Result<ContentResponse, AppError> {
+        let _ = self.git_require_member(ctx, wk, repo).await?;
+        self.git_contents_get(ctx, wk, repo, path, ref_name).await
+    }
+    pub async fn git_contents_create_by_name(&self, ctx: &Session, wk: &str, repo: &str, path: &str, params: CreateContent) -> Result<ContentResponse, AppError> {
+        let _ = self.git_require_member(ctx, wk, repo).await?;
+        self.git_contents_create(ctx, wk, repo, path, params).await
+    }
+    pub async fn git_contents_update_by_name(&self, ctx: &Session, wk: &str, repo: &str, path: &str, params: UpdateContent) -> Result<ContentResponse, AppError> {
+        let _ = self.git_require_member(ctx, wk, repo).await?;
+        self.git_contents_update(ctx, wk, repo, path, params).await
+    }
+    pub async fn git_contents_delete_by_name(&self, ctx: &Session, wk: &str, repo: &str, path: &str, msg: &str, sha: &str, branch: Option<&str>) -> Result<(), AppError> {
+        let _ = self.git_require_member(ctx, wk, repo).await?;
+        self.git_contents_delete(ctx, wk, repo, path, msg, sha, branch).await
+    }
+}
+
+impl AppService {
+    pub async fn git_contents_get(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        path: &str,
+        _ref_name: Option<&str>,
+    ) -> Result<ContentResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut blob_client = BlobServiceClient::new(self.git.clone());
+
+        let empty_oid = p::ObjectId { value: String::new() };
+
+        let resp = blob_client
+            .blob_load(tonic::Request::new(p::BlobLoadRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(empty_oid.clone()),
+                path: path.to_string(),
+            }))
+            .await.map_err(rpc_err)?.into_inner();
+
+        let is_binary = blob_client
+            .blob_is_binary(tonic::Request::new(p::BlobIsBinaryRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(empty_oid.clone()),
+            }))
+            .await.map(|r| r.into_inner().is_binary).unwrap_or(false);
+
+        let size_resp = blob_client
+            .blob_size(tonic::Request::new(p::BlobSizeRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(empty_oid),
+                path: String::new(),
+            }))
+            .await.map_err(rpc_err)?.into_inner();
+
+        let blob_data = resp.blob;
+        let size = size_resp.size as i64;
+
+        let (encoding, content) = if is_binary {
+            (Some("base64".to_string()), Some(base64_encode(&blob_data)))
+        } else {
+            (None, Some(String::from_utf8_lossy(&blob_data).to_string()))
+        };
+
+        Ok(ContentResponse {
+            path: path.to_string(),
+            name: path.rsplit('/').next().unwrap_or(path).to_string(),
+            content_type: "file".to_string(),
+            size,
+            encoding,
+            content,
+        })
+    }
+
+    pub async fn git_contents_create(
+        &self, ctx: &Session, wk_name: &str, repo_name: &str, path: &str,
+        params: CreateContent,
+    ) -> Result<ContentResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let user = crate::session_user(ctx)?;
+
+        let user_model = sqlx::query_as::<_, model::users::UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+             last_sign_in_at, created_at, updated_at FROM \"user\" WHERE id = $1",
+        )
+        .bind(user)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        let display = user_model.display_name.clone();
+        let username = user_model.username.clone();
+        let author_name = if display.is_empty() { username.clone() } else { display };
+
+        let file_size = params.content.len() as i64;
+        let content_bytes = params.content.clone().into_bytes();
+        let mut client = p::commit_service_client::CommitServiceClient::new(self.git.clone());
+        let resp = client
+            .create_commit(tonic::Request::new(p::CreateCommitRequest {
+                repo_id: repo.id.to_string(),
+                branch: params.branch.unwrap_or_else(|| repo.default_branch.clone()),
+                message: params.message,
+                author_name: author_name.clone(),
+                author_email: format!("{username}@gitdata.ai"),
+                committer_name: "redpanda".to_string(),
+                committer_email: "redpanda@gitdata.ai".to_string(),
+                files: vec![p::FileChange {
+                    path: path.to_string(),
+                    content: content_bytes,
+                }],
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let _oid = resp.oid.map(|o| o.value).unwrap_or_default();
+        Ok(ContentResponse {
+            path: path.to_string(),
+            name: path.rsplit('/').next().unwrap_or(path).to_string(),
+            content_type: "file".to_string(),
+            size: file_size,
+            encoding: None,
+            content: Some(params.content),
+        })
+    }
+
+    pub async fn git_contents_update(
+        &self, _ctx: &Session, _wk: &str, _repo: &str, _path: &str,
+        _params: UpdateContent,
+    ) -> Result<ContentResponse, AppError> {
+        Err(AppError::InternalServerError("contents update not yet implemented".to_string()))
+    }
+
+    pub async fn git_contents_delete(
+        &self, _ctx: &Session, _wk: &str, _repo: &str, _path: &str,
+        _message: &str, _sha: &str, _branch: Option<&str>,
+    ) -> Result<(), AppError> {
+        Err(AppError::InternalServerError("contents delete not yet implemented".to_string()))
+    }
+}
+
+fn base64_encode(data: &[u8]) -> String {
+    use base64::Engine as _;
+    base64::engine::general_purpose::STANDARD.encode(data)
+}
diff --git a/lib/service/git/contributor.rs b/lib/service/git/contributor.rs
new file mode 100644
index 0000000..2ed9c90
--- /dev/null
+++ b/lib/service/git/contributor.rs
@@ -0,0 +1,56 @@
+use db::sqlx;
+use serde::{Deserialize, Serialize};
+use session::Session;
+use utoipa::ToSchema;
+
+use crate::{AppService, Pagination, error::AppError};
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ContributorDto {
+    pub name: String,
+    pub email: String,
+    #[schema(value_type = Option<String>)]
+    pub user_id: Option<uuid::Uuid>,
+    pub commit_count: i64,
+}
+
+impl AppService {
+    pub async fn git_repo_contributors(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<ContributorDto>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let offset = pagination.offset() as i64;
+        let limit = pagination.limit() as i64;
+
+        let rows = sqlx::query_as::<_, (String, String, Option<uuid::Uuid>, Option<i64>)>(
+            "SELECT rc.name, rc.email, rc.user, COUNT(rco.id)::bigint AS commit_count \
+             FROM repo_committer rc \
+             LEFT JOIN repo_commit rco ON rc.id = rco.author \
+             WHERE rc.repo = $1 \
+             GROUP BY rc.id, rc.name, rc.email, rc.user \
+             ORDER BY commit_count DESC \
+             OFFSET $2 LIMIT $3",
+        )
+        .bind(repo.id)
+        .bind(offset)
+        .bind(limit)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(|(name, email, user_id, commit_count)| ContributorDto {
+                name,
+                email,
+                user_id,
+                commit_count: commit_count.unwrap_or(0),
+            })
+            .collect())
+    }
+}
diff --git a/lib/service/git/diff.rs b/lib/service/git/diff.rs
new file mode 100644
index 0000000..12e3a03
--- /dev/null
+++ b/lib/service/git/diff.rs
@@ -0,0 +1,128 @@
+use git::rpc::{proto as p, proto::diff_service_client::DiffServiceClient};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_diff_stats(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        old_oid: String,
+        new_oid: String,
+        options: Option<p::DiffOptions>,
+    ) -> Result<p::DiffStatsResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = DiffServiceClient::new(self.git.clone());
+        let resp = client
+            .diff_stats(tonic::Request::new(p::DiffStatsRequest {
+                repo_id: repo.id.to_string(),
+                old_oid: Some(p::ObjectId { value: old_oid }),
+                new_oid: Some(p::ObjectId { value: new_oid }),
+                options,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_diff_patch(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        old_oid: String,
+        new_oid: String,
+        options: Option<p::DiffOptions>,
+    ) -> Result<p::DiffPatchResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = DiffServiceClient::new(self.git.clone());
+        let resp = client
+            .diff_patch(tonic::Request::new(p::DiffPatchRequest {
+                repo_id: repo.id.to_string(),
+                old_oid: Some(p::ObjectId { value: old_oid }),
+                new_oid: Some(p::ObjectId { value: new_oid }),
+                options,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_diff_patch_side_by_side(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        old_oid: String,
+        new_oid: String,
+        options: Option<p::DiffOptions>,
+    ) -> Result<p::DiffPatchSideBySideResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = DiffServiceClient::new(self.git.clone());
+        let resp = client
+            .diff_patch_side_by_side(tonic::Request::new(
+                p::DiffPatchSideBySideRequest {
+                    repo_id: repo.id.to_string(),
+                    old_oid: Some(p::ObjectId { value: old_oid }),
+                    new_oid: Some(p::ObjectId { value: new_oid }),
+                    options,
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_diff_tree_to_tree(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        old_tree: String,
+        new_tree: String,
+        options: Option<p::DiffOptions>,
+    ) -> Result<p::DiffTreeToTreeResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = DiffServiceClient::new(self.git.clone());
+        let resp = client
+            .diff_tree_to_tree(tonic::Request::new(p::DiffTreeToTreeRequest {
+                repo_id: repo.id.to_string(),
+                old_tree: Some(p::ObjectId { value: old_tree }),
+                new_tree: Some(p::ObjectId { value: new_tree }),
+                options,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_diff_index_to_tree(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        tree_oid: String,
+        options: Option<p::DiffOptions>,
+    ) -> Result<p::DiffIndexToTreeResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = DiffServiceClient::new(self.git.clone());
+        let resp = client
+            .diff_index_to_tree(tonic::Request::new(
+                p::DiffIndexToTreeRequest {
+                    repo_id: repo.id.to_string(),
+                    tree_oid: Some(p::ObjectId { value: tree_oid }),
+                    options,
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/fork.rs b/lib/service/git/fork.rs
new file mode 100644
index 0000000..92e9a4a
--- /dev/null
+++ b/lib/service/git/fork.rs
@@ -0,0 +1,204 @@
+use db::sqlx;
+use git::rpc::{proto as p, proto::fork_service_client::ForkServiceClient};
+use model::repos::RepoModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct ForkResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+    pub description: Option<String>,
+    pub default_branch: String,
+    pub visibility: String,
+    #[schema(value_type = String)]
+    pub source_repo: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub forked_by: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateFork {
+    pub name: Option<String>,
+    pub visibility: Option<String>,
+}
+
+#[derive(db::sqlx::FromRow)]
+struct ForkListRow {
+    source_repo: uuid::Uuid,
+    forked_by: uuid::Uuid,
+    fork_created_at: chrono::DateTime<chrono::Utc>,
+    repo_id: uuid::Uuid,
+    repo_name: String,
+    repo_description: Option<String>,
+    repo_default_branch: String,
+    repo_visibility: String,
+}
+
+impl AppService {
+    pub async fn repo_fork_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: CreateFork,
+    ) -> Result<ForkResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let src_wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(src_wk.id, user_uid).await?;
+        let source_repo = self.repo_resolve(src_wk.id, repo_name).await?;
+
+        if source_repo.visibility == "private" {
+            return Err(AppError::Forbidden(
+                "cannot fork a private repo".to_string(),
+            ));
+        }
+
+        let fork_name = params.name.unwrap_or_else(|| source_repo.name.clone());
+        let fork_visibility = params
+            .visibility
+            .unwrap_or_else(|| source_repo.visibility.clone());
+
+        let existing = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL AND created_by = $3)",
+        )
+        .bind(src_wk.id)
+        .bind(&fork_name)
+        .bind(user_uid)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        if existing {
+            return Err(AppError::Conflict("fork already exists".to_string()));
+        }
+
+        let repo_id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+        let description = source_repo.description.clone();
+        let default_branch = source_repo.default_branch.clone();
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+        let _fork_repo = sqlx::query_as::<_, RepoModel>(
+            "INSERT INTO repo (id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, 0, false, false, false, $7, '', $8, $8) \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(repo_id)
+        .bind(src_wk.id)
+        .bind(&fork_name)
+        .bind(&description)
+        .bind(&default_branch)
+        .bind(&fork_visibility)
+        .bind(user_uid)
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let storage_root = self
+            .config
+            .repos_root()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let mut client = ForkServiceClient::new(self.git.clone());
+        let rpc_resp = client
+            .fork_bare(tonic::Request::new(p::ForkBareRequest {
+                storage_root,
+                source_storage_path: source_repo.storage_path.clone(),
+                params: Some(p::ForkRepoParams {
+                    namespace: src_wk.name.clone(),
+                    repo_name: fork_name.clone(),
+                    default_branch: default_branch.clone(),
+                    description: description.clone(),
+                    enable_lfs: false,
+                }),
+            }))
+            .await
+            .map_err(crate::git::rpc_err)?
+            .into_inner();
+        let fork_repo = sqlx::query_as::<_, RepoModel>(
+            "UPDATE repo SET storage_path = $1 WHERE id = $2 \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(&rpc_resp.storage_path)
+        .bind(repo_id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        sqlx::query(
+            "INSERT INTO repo_fork (id, repo, source_repo, forked_by, created_at) \
+             VALUES ($1, $2, $3, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(fork_repo.id)
+        .bind(source_repo.id)
+        .bind(user_uid)
+        .bind(now)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        self.queue_sync(repo_id).await;
+
+        Ok(ForkResponse {
+            id: fork_repo.id,
+            name: fork_repo.name,
+            description: fork_repo.description,
+            default_branch: fork_repo.default_branch,
+            visibility: fork_repo.visibility,
+            source_repo: source_repo.id,
+            forked_by: user_uid,
+            created_at: fork_repo.created_at,
+        })
+    }
+
+    pub async fn repo_fork_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<ForkResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let rows = sqlx::query_as::<_, ForkListRow>(
+            "SELECT f.id as fork_id, f.source_repo, f.forked_by, f.created_at as fork_created_at, \
+             r.id as repo_id, r.name as repo_name, r.description as repo_description, \
+             r.default_branch as repo_default_branch, r.visibility as repo_visibility, \
+             r.created_at as repo_created_at \
+             FROM repo_fork f \
+             INNER JOIN repo r ON r.id = f.repo AND r.deleted_at IS NULL \
+             WHERE f.source_repo = $1 \
+             ORDER BY f.created_at DESC \
+             OFFSET $2 LIMIT $3",
+        )
+        .bind(repo.id)
+        .bind(pagination.offset() as i64)
+        .bind(pagination.limit() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(|row| ForkResponse {
+                id: row.repo_id,
+                name: row.repo_name,
+                description: row.repo_description,
+                default_branch: row.repo_default_branch,
+                visibility: row.repo_visibility,
+                source_repo: row.source_repo,
+                forked_by: row.forked_by,
+                created_at: row.fork_created_at,
+            })
+            .collect())
+    }
+}
diff --git a/lib/service/git/init.rs b/lib/service/git/init.rs
new file mode 100644
index 0000000..9140d2c
--- /dev/null
+++ b/lib/service/git/init.rs
@@ -0,0 +1,217 @@
+use db::sqlx;
+use git::rpc::{proto as p, proto::init_service_client::InitServiceClient};
+use model::repos::RepoModel;
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err, session_user};
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct CreateRepo {
+    pub name: String,
+    pub description: Option<String>,
+    pub default_branch: Option<String>,
+    pub visibility: Option<String>,
+    pub initialize_with_readme: Option<bool>,
+    pub enable_lfs: Option<bool>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct CloneRepo {
+    pub name: String,
+    pub source_url: String,
+    pub description: Option<String>,
+    pub visibility: Option<String>,
+}
+
+impl AppService {
+    pub async fn git_init_bare(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        params: CreateRepo,
+    ) -> Result<RepoModel, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let name = params.name.trim();
+        if name.is_empty() {
+            return Err(AppError::BadRequest(
+                "repo name is required".to_string(),
+            ));
+        }
+
+        let existing = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL)",
+        )
+        .bind(wk.id)
+        .bind(name)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if existing {
+            return Err(AppError::RepoNameAlreadyExists);
+        }
+
+        let default_branch =
+            params.default_branch.unwrap_or_else(|| "main".to_string());
+        let visibility =
+            params.visibility.unwrap_or_else(|| "private".to_string());
+        let description = params.description.unwrap_or_default();
+        let now = chrono::Utc::now();
+        let repo_id = uuid::Uuid::now_v7();
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let _repo = sqlx::query_as::<_, RepoModel>(
+            "INSERT INTO repo (id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, 0, false, false, false, $7, '', $8, $8) \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(repo_id)
+        .bind(wk.id)
+        .bind(name)
+        .bind(&description)
+        .bind(&default_branch)
+        .bind(&visibility)
+        .bind(user_uid)
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let storage_root = self
+            .config
+            .repos_root()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let mut client = InitServiceClient::new(self.git.clone());
+        let rpc_resp = client
+            .init_bare(tonic::Request::new(p::InitBareRequest {
+                storage_root,
+                params: Some(p::InitRepoParams {
+                    namespace: wk.name.clone(),
+                    repo_name: name.to_string(),
+                    default_branch,
+                    description: Some(description),
+                    initialize_with_readme: params
+                        .initialize_with_readme
+                        .unwrap_or(false),
+                    enable_lfs: params.enable_lfs.unwrap_or(false),
+                }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let repo = sqlx::query_as::<_, RepoModel>(
+            "UPDATE repo SET storage_path = $1 WHERE id = $2 \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(&rpc_resp.storage_path)
+        .bind(repo_id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        self.queue_sync(repo_id).await;
+        Ok(repo)
+    }
+
+    pub async fn git_clone_bare(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        params: CloneRepo,
+    ) -> Result<RepoModel, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let name = params.name.trim();
+        if name.is_empty() {
+            return Err(AppError::BadRequest("repo name is required".to_string()));
+        }
+
+        let source_url = params.source_url.trim();
+        if source_url.is_empty() {
+            return Err(AppError::BadRequest("source URL is required".to_string()));
+        }
+
+        let existing = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL)",
+        )
+        .bind(wk.id)
+        .bind(name)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if existing {
+            return Err(AppError::RepoNameAlreadyExists);
+        }
+
+        let visibility =
+            params.visibility.unwrap_or_else(|| "private".to_string());
+        let description = params.description.unwrap_or_default();
+        let now = chrono::Utc::now();
+        let repo_id = uuid::Uuid::now_v7();
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let _repo = sqlx::query_as::<_, RepoModel>(
+            "INSERT INTO repo (id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, '', $5, 0, false, false, true, $6, '', $7, $7) \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(repo_id)
+        .bind(wk.id)
+        .bind(name)
+        .bind(&description)
+        .bind(&visibility)
+        .bind(user_uid)
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let storage_root = self
+            .config
+            .repos_root()
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        let mut client = InitServiceClient::new(self.git.clone());
+        let rpc_resp = client
+            .clone_bare(tonic::Request::new(p::CloneBareRequest {
+                storage_root,
+                source_url: source_url.to_string(),
+                namespace: wk.name.clone(),
+                repo_name: name.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let repo = sqlx::query_as::<_, RepoModel>(
+            "UPDATE repo SET storage_path = $1 WHERE id = $2 \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(&rpc_resp.storage_path)
+        .bind(repo_id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        self.queue_sync(repo_id).await;
+        Ok(repo)
+    }
+}
diff --git a/lib/service/git/language.rs b/lib/service/git/language.rs
new file mode 100644
index 0000000..350d97c
--- /dev/null
+++ b/lib/service/git/language.rs
@@ -0,0 +1,42 @@
+use db::sqlx;
+use serde::{Deserialize, Serialize};
+use session::Session;
+use utoipa::ToSchema;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct LanguageStatDto {
+    pub language: String,
+    pub bytes: i64,
+    pub percentage: f32,
+}
+
+impl AppService {
+    pub async fn git_repo_languages(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<Vec<LanguageStatDto>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let rows = sqlx::query_as::<_, (String, i64, f32)>(
+            "SELECT language, bytes, percentage FROM repo_language WHERE repo = $1 \
+             ORDER BY bytes DESC",
+        )
+        .bind(repo.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(|(language, bytes, percentage)| LanguageStatDto {
+                language,
+                bytes,
+                percentage,
+            })
+            .collect())
+    }
+}
diff --git a/lib/service/git/mod.rs b/lib/service/git/mod.rs
new file mode 100644
index 0000000..cfe1078
--- /dev/null
+++ b/lib/service/git/mod.rs
@@ -0,0 +1,95 @@
+pub mod archive;
+pub mod blame;
+pub mod blob;
+pub mod branch;
+pub mod commit;
+pub mod commit_status;
+pub mod compare;
+pub mod contents;
+pub mod contributor;
+pub mod diff;
+pub mod fork;
+pub mod init;
+pub mod language;
+pub mod protect;
+pub mod readme;
+pub mod refs;
+pub mod release;
+pub mod repo;
+pub mod star;
+pub mod tag;
+pub mod tree;
+pub mod watch;
+pub mod webhook;
+
+use db::sqlx;
+use git::sync::{ReceiveSyncService, RepoReceiveSyncTask};
+use model::repos::RepoModel;
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+impl AppService {
+    pub(crate) async fn queue_sync(&self, repo_uid: uuid::Uuid) {
+        let sync_service = ReceiveSyncService::new(self.redis_pool.clone());
+        sync_service.send(RepoReceiveSyncTask { repo_uid }).await;
+    }
+
+    pub(crate) async fn repo_resolve(
+        &self,
+        wk_id: uuid::Uuid,
+        repo_name: &str,
+    ) -> Result<RepoModel, AppError> {
+        sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at \
+             FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL",
+        )
+        .bind(wk_id)
+        .bind(repo_name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::RepoNotFound)
+    }
+
+    pub(crate) async fn git_require_member(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<RepoModel, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        self.repo_resolve(wk.id, repo_name).await
+    }
+
+    pub(crate) async fn git_require_admin(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<RepoModel, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        self.repo_resolve(wk.id, repo_name).await
+    }
+}
+
+pub(crate) fn rpc_err(status: tonic::Status) -> AppError {
+    match status.code() {
+        tonic::Code::NotFound => {
+            AppError::NotFound(status.message().to_string())
+        }
+        tonic::Code::PermissionDenied => AppError::PermissionDenied,
+        tonic::Code::InvalidArgument => {
+            AppError::BadRequest(status.message().to_string())
+        }
+        tonic::Code::AlreadyExists => {
+            AppError::Conflict(status.message().to_string())
+        }
+        _ => AppError::GitRpcError(status.message().to_string()),
+    }
+}
diff --git a/lib/service/git/protect.rs b/lib/service/git/protect.rs
new file mode 100644
index 0000000..7bd369e
--- /dev/null
+++ b/lib/service/git/protect.rs
@@ -0,0 +1,259 @@
+use db::sqlx;
+use model::repos::RepoProtectModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct ProtectResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub repo: uuid::Uuid,
+    pub pattern: String,
+    pub require_pull_request: bool,
+    pub required_approvals: i32,
+    pub require_status_checks: bool,
+    pub required_status_contexts: Vec<String>,
+    pub enforce_admins: bool,
+    pub allow_force_pushes: bool,
+    pub allow_deletions: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub(crate) fn protect_response(p: RepoProtectModel) -> ProtectResponse {
+    ProtectResponse {
+        id: p.id,
+        repo: p.repo,
+        pattern: p.pattern,
+        require_pull_request: p.require_pull_request,
+        required_approvals: p.required_approvals,
+        require_status_checks: p.require_status_checks,
+        required_status_contexts: p
+            .required_status_contexts
+            .split('.')
+            .filter(|s| !s.is_empty())
+            .map(|s| s.to_string())
+            .collect(),
+        enforce_admins: p.enforce_admins,
+        allow_force_pushes: p.allow_force_pushes,
+        allow_deletions: p.allow_deletions,
+        created_at: p.created_at,
+        updated_at: p.updated_at,
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateProtect {
+    pub pattern: String,
+    pub require_pull_request: Option<bool>,
+    pub required_approvals: Option<i32>,
+    pub require_status_checks: Option<bool>,
+    pub required_status_contexts: Option<Vec<String>>,
+    pub enforce_admins: Option<bool>,
+    pub allow_force_pushes: Option<bool>,
+    pub allow_deletions: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateProtect {
+    pub pattern: Option<String>,
+    pub require_pull_request: Option<bool>,
+    pub required_approvals: Option<i32>,
+    pub require_status_checks: Option<bool>,
+    pub required_status_contexts: Option<Vec<String>>,
+    pub enforce_admins: Option<bool>,
+    pub allow_force_pushes: Option<bool>,
+    pub allow_deletions: Option<bool>,
+}
+
+impl AppService {
+    pub async fn repo_protect_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<ProtectResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let rows = sqlx::query_as::<_, RepoProtectModel>(
+            "SELECT id, repo, pattern, require_pull_request, required_approvals, \
+             require_status_checks, required_status_contexts, enforce_admins, \
+             allow_force_pushes, allow_deletions, created_at, updated_at \
+             FROM repo_protect WHERE repo = $1 \
+             ORDER BY pattern ASC OFFSET $2 LIMIT $3",
+        )
+        .bind(repo.id)
+        .bind(pagination.offset() as i64)
+        .bind(pagination.limit() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(protect_response).collect())
+    }
+
+    pub async fn repo_protect_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: CreateProtect,
+    ) -> Result<ProtectResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let pattern = params.pattern.trim();
+        if pattern.is_empty() {
+            return Err(AppError::BadRequest(
+                "pattern is required".to_string(),
+            ));
+        }
+
+        let contexts = params
+            .required_status_contexts
+            .unwrap_or_default()
+            .join(".");
+
+        let id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+
+        let row = sqlx::query_as::<_, RepoProtectModel>(
+            "INSERT INTO repo_protect \
+             (id, repo, pattern, require_pull_request, required_approvals, \
+              require_status_checks, required_status_contexts, enforce_admins, \
+              allow_force_pushes, allow_deletions, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $11) \
+             RETURNING id, repo, pattern, require_pull_request, required_approvals, \
+              require_status_checks, required_status_contexts, enforce_admins, \
+              allow_force_pushes, allow_deletions, created_at, updated_at",
+        )
+        .bind(id)
+        .bind(repo.id)
+        .bind(pattern)
+        .bind(params.require_pull_request.unwrap_or(true))
+        .bind(params.required_approvals.unwrap_or(1))
+        .bind(params.require_status_checks.unwrap_or(false))
+        .bind(&contexts)
+        .bind(params.enforce_admins.unwrap_or(false))
+        .bind(params.allow_force_pushes.unwrap_or(false))
+        .bind(params.allow_deletions.unwrap_or(false))
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(protect_response(row))
+    }
+
+    pub async fn repo_protect_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        protect_id: uuid::Uuid,
+        params: UpdateProtect,
+    ) -> Result<ProtectResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let existing = sqlx::query_as::<_, RepoProtectModel>(
+            "SELECT id, repo, pattern, require_pull_request, required_approvals, \
+             require_status_checks, required_status_contexts, enforce_admins, \
+             allow_force_pushes, allow_deletions, created_at, updated_at \
+             FROM repo_protect WHERE id = $1 AND repo = $2",
+        )
+        .bind(protect_id)
+        .bind(repo.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("protected branch rule not found".to_string()))?;
+
+        let pattern = params.pattern.unwrap_or(existing.pattern);
+        let require_pull_request = params
+            .require_pull_request
+            .unwrap_or(existing.require_pull_request);
+        let required_approvals = params
+            .required_approvals
+            .unwrap_or(existing.required_approvals);
+        let require_status_checks = params
+            .require_status_checks
+            .unwrap_or(existing.require_status_checks);
+        let contexts = params
+            .required_status_contexts
+            .map(|c| c.join("."))
+            .unwrap_or(existing.required_status_contexts);
+        let enforce_admins =
+            params.enforce_admins.unwrap_or(existing.enforce_admins);
+        let allow_force_pushes = params
+            .allow_force_pushes
+            .unwrap_or(existing.allow_force_pushes);
+        let allow_deletions =
+            params.allow_deletions.unwrap_or(existing.allow_deletions);
+
+        let row = sqlx::query_as::<_, RepoProtectModel>(
+            "UPDATE repo_protect SET \
+             pattern = $1, require_pull_request = $2, required_approvals = $3, \
+             require_status_checks = $4, required_status_contexts = $5, enforce_admins = $6, \
+             allow_force_pushes = $7, allow_deletions = $8, updated_at = $9 \
+             WHERE id = $10 \
+             RETURNING id, repo, pattern, require_pull_request, required_approvals, \
+              require_status_checks, required_status_contexts, enforce_admins, \
+              allow_force_pushes, allow_deletions, created_at, updated_at",
+        )
+        .bind(&pattern)
+        .bind(require_pull_request)
+        .bind(required_approvals)
+        .bind(require_status_checks)
+        .bind(&contexts)
+        .bind(enforce_admins)
+        .bind(allow_force_pushes)
+        .bind(allow_deletions)
+        .bind(chrono::Utc::now())
+        .bind(protect_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(protect_response(row))
+    }
+
+    pub async fn repo_protect_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        protect_id: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let result =
+            sqlx::query("DELETE FROM repo_protect WHERE id = $1 AND repo = $2")
+                .bind(protect_id)
+                .bind(repo.id)
+                .execute(self.db.writer())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if result.rows_affected() == 0 {
+            return Err(AppError::NotFound(
+                "protected branch rule not found".to_string(),
+            ));
+        }
+
+        Ok(())
+    }
+}
diff --git a/lib/service/git/readme.rs b/lib/service/git/readme.rs
new file mode 100644
index 0000000..d7e252c
--- /dev/null
+++ b/lib/service/git/readme.rs
@@ -0,0 +1,139 @@
+use serde::{Deserialize, Serialize};
+use session::Session;
+use utoipa::ToSchema;
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ReadmeDto {
+    pub content: String,
+    pub html: String,
+}
+
+impl AppService {
+    pub async fn git_repo_readme(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<Option<ReadmeDto>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let readme_names = [
+            "README.md",
+            "README.markdown",
+            "README.txt",
+            "README",
+            "Readme.md",
+            "readme.md",
+        ];
+
+        for name in &readme_names {
+            match self
+                .git_tree_entry_by_path_from_commit_for_readme(
+                    &repo.id,
+                    name,
+                )
+                .await?
+            {
+                Some((content, oid)) => {
+                    return self
+                        .git_blob_load_for_readme(
+                            &repo, &content, &oid,
+                        )
+                        .await;
+                }
+                None => continue,
+            }
+        }
+
+        Ok(None)
+    }
+}
+impl AppService {
+    async fn git_tree_entry_by_path_from_commit_for_readme(
+        &self,
+        repo_id: &uuid::Uuid,
+        readme_name: &str,
+    ) -> Result<Option<(String, String)>, AppError> {
+        use git::rpc::proto as p;
+        use git::rpc::proto::tree_service_client::TreeServiceClient;
+        use crate::git::rpc_err;
+
+        let mut client = TreeServiceClient::new(self.git.clone());
+        let mut commit_client =
+            git::rpc::proto::commit_service_client::CommitServiceClient::new(self.git.clone());
+        let summary_resp = commit_client
+            .commit_summary(tonic::Request::new(p::CommitSummaryRequest {
+                repo_id: repo_id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let head_commit = match summary_resp.summary.and_then(|s| s.head) {
+            Some(c) => c,
+            None => return Ok(None),
+        };
+
+        let tree_id = match head_commit.tree_id {
+            Some(id) => id.value,
+            None => return Ok(None),
+        };
+
+        let resp = client
+            .tree_entry_by_path(tonic::Request::new(p::TreeEntryByPathRequest {
+                repo_id: repo_id.to_string(),
+                tree_oid: Some(p::ObjectId { value: tree_id.clone() }),
+                path: readme_name.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        match resp.entry {
+            Some(entry) => {
+                let oid = entry.oid.map(|o| o.value).unwrap_or_default();
+                if oid.is_empty() {
+                    Ok(None)
+                } else {
+                    Ok(Some((readme_name.to_string(), oid)))
+                }
+            }
+            None => Ok(None),
+        }
+    }
+    async fn git_blob_load_for_readme(
+        &self,
+        repo: &model::repos::RepoModel,
+        _path: &str,
+        oid: &str,
+    ) -> Result<Option<super::readme::ReadmeDto>, AppError> {
+        use git::rpc::proto as p;
+        use git::rpc::proto::blob_service_client::BlobServiceClient;
+        use crate::git::rpc_err;
+
+        let mut client = BlobServiceClient::new(self.git.clone());
+        let resp = client
+            .blob_load(tonic::Request::new(p::BlobLoadRequest {
+                repo_id: repo.id.to_string(),
+                id: Some(p::ObjectId { value: oid.to_string() }),
+                path: String::new(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let content = String::from_utf8_lossy(&resp.blob).to_string();
+        if content.is_empty() {
+            return Ok(None);
+        }
+
+        let html = comrak::markdown_to_html(&content, &comrak::ComrakOptions::default());
+
+        Ok(Some(super::readme::ReadmeDto {
+            content,
+            html,
+        }))
+    }
+}
diff --git a/lib/service/git/refs.rs b/lib/service/git/refs.rs
new file mode 100644
index 0000000..e861daa
--- /dev/null
+++ b/lib/service/git/refs.rs
@@ -0,0 +1,76 @@
+use db::sqlx;
+use model::repos::RepoRefModel;
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct GitRefResponse {
+    pub name: String,
+    pub kind: String,
+    pub target_sha: String,
+    pub is_default: bool,
+    pub is_protected: bool,
+}
+
+impl AppService {
+    pub async fn git_ref_list_by_name(&self, ctx: &Session, wk: &str, repo: &str) -> Result<Vec<GitRefResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_ref_list(repo.id).await
+    }
+    pub async fn git_ref_get_by_name(&self, ctx: &Session, wk: &str, repo: &str, ref_name: &str) -> Result<GitRefResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_ref_get(repo.id, ref_name).await
+    }
+}
+
+impl AppService {
+    pub async fn git_ref_list(
+        &self,
+        repo_id: Uuid,
+    ) -> Result<Vec<GitRefResponse>, AppError> {
+        let refs = sqlx::query_as::<_, RepoRefModel>(
+            "SELECT id, repo, name, kind, target_sha, is_default, is_protected, \
+             created_at, updated_at FROM repo_ref WHERE repo = $1 ORDER BY name",
+        )
+        .bind(repo_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(refs.into_iter().map(|r| GitRefResponse {
+            name: r.name,
+            kind: r.kind,
+            target_sha: r.target_sha,
+            is_default: r.is_default,
+            is_protected: r.is_protected,
+        }).collect())
+    }
+
+    pub async fn git_ref_get(
+        &self,
+        repo_id: Uuid,
+        ref_name: &str,
+    ) -> Result<GitRefResponse, AppError> {
+        let r = sqlx::query_as::<_, RepoRefModel>(
+            "SELECT id, repo, name, kind, target_sha, is_default, is_protected, \
+             created_at, updated_at FROM repo_ref WHERE repo = $1 AND name = $2",
+        )
+        .bind(repo_id)
+        .bind(ref_name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("ref not found".to_string()))?;
+
+        Ok(GitRefResponse {
+            name: r.name,
+            kind: r.kind,
+            target_sha: r.target_sha,
+            is_default: r.is_default,
+            is_protected: r.is_protected,
+        })
+    }
+}
diff --git a/lib/service/git/release.rs b/lib/service/git/release.rs
new file mode 100644
index 0000000..967d8b9
--- /dev/null
+++ b/lib/service/git/release.rs
@@ -0,0 +1,386 @@
+use chrono::Utc;
+use db::sqlx;
+use model::repos::{
+    RepoReleaseAssetModel, RepoReleaseModel,
+};
+use session::Session;
+use uuid::Uuid;
+
+use crate::error::AppError;
+use crate::AppService;
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct ReleaseResponse {
+    pub id: Uuid,
+    pub tag_name: String,
+    pub target_commit_sha: String,
+    pub name: String,
+    pub body: Option<String>,
+    pub draft: bool,
+    pub prerelease: bool,
+    pub author: Uuid,
+    pub assets: Vec<ReleaseAssetResponse>,
+    pub published_at: Option<chrono::DateTime<Utc>>,
+    pub created_at: chrono::DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)]
+pub struct ReleaseAssetResponse {
+    pub id: Uuid,
+    pub name: String,
+    pub content_type: Option<String>,
+    pub size: i64,
+    pub download_count: i64,
+    pub created_at: chrono::DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct CreateRelease {
+    pub tag_name: String,
+    pub target_commit_sha: Option<String>,
+    pub name: String,
+    pub body: Option<String>,
+    #[serde(default)]
+    pub draft: bool,
+    #[serde(default)]
+    pub prerelease: bool,
+}
+
+#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)]
+pub struct UpdateRelease {
+    pub tag_name: Option<String>,
+    pub name: Option<String>,
+    pub body: Option<Option<String>>,
+    pub draft: Option<bool>,
+    pub prerelease: Option<bool>,
+}
+
+impl AppService {
+    pub async fn git_release_list(
+        &self,
+        repo_id: Uuid,
+    ) -> Result<Vec<ReleaseResponse>, AppError> {
+        let releases = sqlx::query_as::<_, RepoReleaseModel>(
+            "SELECT id, repo, tag_name, target_commit_sha, name, body, \
+             draft, prerelease, author, published_at, created_at, updated_at \
+             FROM repo_release WHERE repo = $1 ORDER BY created_at DESC LIMIT 50",
+        )
+        .bind(repo_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut result = Vec::with_capacity(releases.len());
+        for r in releases {
+            let assets = self.git_release_assets(r.id).await?;
+            result.push(release_to_response(r, assets));
+        }
+        Ok(result)
+    }
+
+    pub async fn git_release_get(
+        &self,
+        repo_id: Uuid,
+        release_id: Uuid,
+    ) -> Result<ReleaseResponse, AppError> {
+        let r = sqlx::query_as::<_, RepoReleaseModel>(
+            "SELECT id, repo, tag_name, target_commit_sha, name, body, \
+             draft, prerelease, author, published_at, created_at, updated_at \
+             FROM repo_release WHERE id = $1 AND repo = $2",
+        )
+        .bind(release_id)
+        .bind(repo_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("release not found".to_string()))?;
+
+        let assets = self.git_release_assets(r.id).await?;
+        Ok(release_to_response(r, assets))
+    }
+
+    pub async fn git_release_get_by_tag(
+        &self,
+        repo_id: Uuid,
+        tag: &str,
+    ) -> Result<ReleaseResponse, AppError> {
+        let r = sqlx::query_as::<_, RepoReleaseModel>(
+            "SELECT id, repo, tag_name, target_commit_sha, name, body, \
+             draft, prerelease, author, published_at, created_at, updated_at \
+             FROM repo_release WHERE repo = $1 AND tag_name = $2",
+        )
+        .bind(repo_id)
+        .bind(tag)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("release not found".to_string()))?;
+
+        let assets = self.git_release_assets(r.id).await?;
+        Ok(release_to_response(r, assets))
+    }
+
+    pub async fn git_release_create(
+        &self,
+        _session: &Session,
+        repo_id: Uuid,
+        user_id: Uuid,
+        params: CreateRelease,
+    ) -> Result<ReleaseResponse, AppError> {
+        let id = Uuid::now_v7();
+        let now = Utc::now();
+        let published_at = if params.draft { None } else { Some(now) };
+
+        let target = if let Some(ref sha) = params.target_commit_sha {
+            if !sha.trim().is_empty() { sha.clone() } else { self.default_branch_sha(repo_id).await? }
+        } else {
+            self.default_branch_sha(repo_id).await?
+        };
+
+        let r = sqlx::query_as::<_, RepoReleaseModel>(
+            "INSERT INTO repo_release (id, repo, tag_name, target_commit_sha, name, body, \
+             draft, prerelease, author, published_at, created_at, updated_at) \
+             VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$11) \
+             RETURNING id, repo, tag_name, target_commit_sha, name, body, \
+             draft, prerelease, author, published_at, created_at, updated_at",
+        )
+        .bind(id)
+        .bind(repo_id)
+        .bind(&params.tag_name)
+        .bind(&target)
+        .bind(&params.name)
+        .bind(&params.body)
+        .bind(params.draft)
+        .bind(params.prerelease)
+        .bind(user_id)
+        .bind(published_at)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(release_to_response(r, Vec::new()))
+    }
+
+    pub async fn git_release_update(
+        &self,
+        repo_id: Uuid,
+        release_id: Uuid,
+        params: UpdateRelease,
+    ) -> Result<ReleaseResponse, AppError> {
+        let existing = self.git_release_get(repo_id, release_id).await?;
+        let now = Utc::now();
+
+        let tag_name = params.tag_name.unwrap_or(existing.tag_name);
+        let name = params.name.unwrap_or(existing.name);
+        let body = params.body.unwrap_or(existing.body);
+        let draft = params.draft.unwrap_or(existing.draft);
+        let prerelease = params.prerelease.unwrap_or(existing.prerelease);
+
+        let published_at = if draft { None } else { existing.published_at.or(Some(now)) };
+
+        let r = sqlx::query_as::<_, RepoReleaseModel>(
+            "UPDATE repo_release SET tag_name=$1, name=$2, body=$3, draft=$4, \
+             prerelease=$5, published_at=$6, updated_at=$7 \
+             WHERE id=$8 AND repo=$9 \
+             RETURNING id, repo, tag_name, target_commit_sha, name, body, \
+             draft, prerelease, author, published_at, created_at, updated_at",
+        )
+        .bind(&tag_name)
+        .bind(&name)
+        .bind(&body)
+        .bind(draft)
+        .bind(prerelease)
+        .bind(published_at)
+        .bind(now)
+        .bind(release_id)
+        .bind(repo_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let assets = self.git_release_assets(r.id).await?;
+        Ok(release_to_response(r, assets))
+    }
+
+    pub async fn git_release_delete(
+        &self,
+        repo_id: Uuid,
+        release_id: Uuid,
+    ) -> Result<(), AppError> {
+        let rows = sqlx::query(
+            "DELETE FROM repo_release WHERE id = $1 AND repo = $2",
+        )
+        .bind(release_id)
+        .bind(repo_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        if rows.rows_affected() == 0 {
+            return Err(AppError::NotFound("release not found".to_string()));
+        }
+        Ok(())
+    }
+
+    pub async fn git_release_delete_by_tag(
+        &self,
+        repo_id: Uuid,
+        tag: &str,
+    ) -> Result<(), AppError> {
+        let release_id: Option<Uuid> = sqlx::query_scalar(
+            "SELECT id FROM repo_release WHERE repo = $1 AND tag_name = $2",
+        )
+        .bind(repo_id)
+        .bind(tag)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let release_id = release_id
+            .ok_or_else(|| AppError::NotFound("release not found".to_string()))?;
+        self.git_release_delete(repo_id, release_id).await
+    }
+
+    async fn git_release_assets(
+        &self,
+        release_id: Uuid,
+    ) -> Result<Vec<ReleaseAssetResponse>, AppError> {
+        let assets = sqlx::query_as::<_, RepoReleaseAssetModel>(
+            "SELECT id, release_id, name, content_type, size, download_count, \
+             storage_path, uploader, created_at \
+             FROM repo_release_asset WHERE release_id = $1 ORDER BY created_at",
+        )
+        .bind(release_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(assets.into_iter().map(|a| ReleaseAssetResponse {
+            id: a.id,
+            name: a.name,
+            content_type: a.content_type,
+            size: a.size,
+            download_count: a.download_count,
+            created_at: a.created_at,
+        }).collect())
+    }
+
+    pub async fn git_release_asset_create(
+        &self,
+        repo_id: Uuid,
+        release_id: Uuid,
+        user_id: Uuid,
+        name: String,
+        content_type: Option<String>,
+        size: i64,
+        storage_path: String,
+    ) -> Result<ReleaseAssetResponse, AppError> {
+        let _ = self.git_release_get(repo_id, release_id).await?;
+
+        let id = Uuid::now_v7();
+        let now = Utc::now();
+        let a = sqlx::query_as::<_, RepoReleaseAssetModel>(
+            "INSERT INTO repo_release_asset (id, release_id, name, content_type, size, \
+             download_count, storage_path, uploader, created_at) \
+             VALUES ($1,$2,$3,$4,$5,0,$6,$7,$8) RETURNING *",
+        )
+        .bind(id)
+        .bind(release_id)
+        .bind(&name)
+        .bind(&content_type)
+        .bind(size)
+        .bind(&storage_path)
+        .bind(user_id)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(ReleaseAssetResponse {
+            id: a.id,
+            name: a.name,
+            content_type: a.content_type,
+            size: a.size,
+            download_count: a.download_count,
+            created_at: a.created_at,
+        })
+    }
+
+    pub async fn git_release_asset_delete(
+        &self,
+        repo_id: Uuid,
+        release_id: Uuid,
+        asset_id: Uuid,
+    ) -> Result<(), AppError> {
+        let _ = self.git_release_get(repo_id, release_id).await?;
+        sqlx::query(
+            "DELETE FROM repo_release_asset WHERE id = $1 AND release_id = $2",
+        )
+        .bind(asset_id)
+        .bind(release_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+}
+
+impl AppService {
+    pub async fn git_release_list_by_name(&self, ctx: &Session, _user_id: Uuid, wk: &str, repo: &str) -> Result<Vec<ReleaseResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_list(repo.id).await
+    }
+    pub async fn git_release_get_by_name(&self, ctx: &Session, _user_id: Uuid, wk: &str, repo: &str, id: Uuid) -> Result<ReleaseResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_get(repo.id, id).await
+    }
+    pub async fn git_release_get_by_tag_name(&self, ctx: &Session, _user_id: Uuid, wk: &str, repo: &str, tag: &str) -> Result<ReleaseResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_get_by_tag(repo.id, tag).await
+    }
+    pub async fn git_release_create_by_name(&self, ctx: &Session, user_id: Uuid, wk: &str, repo: &str, params: CreateRelease) -> Result<ReleaseResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_create(ctx, repo.id, user_id, params).await
+    }
+    pub async fn git_release_update_by_name(&self, ctx: &Session, _user_id: Uuid, wk: &str, repo: &str, id: Uuid, params: UpdateRelease) -> Result<ReleaseResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_update(repo.id, id, params).await
+    }
+    pub async fn git_release_delete_by_name(&self, ctx: &Session, _user_id: Uuid, wk: &str, repo: &str, id: Uuid) -> Result<(), AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_delete(repo.id, id).await
+    }
+    pub async fn git_release_delete_by_tag_name(&self, ctx: &Session, _user_id: Uuid, wk: &str, repo: &str, tag: &str) -> Result<(), AppError> {
+        let repo = self.git_require_member(ctx, wk, repo).await?;
+        self.git_release_delete_by_tag(repo.id, tag).await
+    }
+}
+
+impl AppService {
+    async fn default_branch_sha(&self, repo_id: Uuid) -> Result<String, AppError> {
+        sqlx::query_scalar("SELECT target_sha FROM repo_ref WHERE repo = $1 AND is_default = true")
+            .bind(repo_id)
+            .fetch_optional(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+            .ok_or_else(|| AppError::BadRequest("no default branch to target".to_string()))
+    }
+}
+
+fn release_to_response(
+    r: RepoReleaseModel,
+    assets: Vec<ReleaseAssetResponse>,
+) -> ReleaseResponse {
+    ReleaseResponse {
+        id: r.id,
+        tag_name: r.tag_name,
+        target_commit_sha: r.target_commit_sha,
+        name: r.name,
+        body: r.body,
+        draft: r.draft,
+        prerelease: r.prerelease,
+        author: r.author,
+        assets,
+        published_at: r.published_at,
+        created_at: r.created_at,
+    }
+}
diff --git a/lib/service/git/repo.rs b/lib/service/git/repo.rs
new file mode 100644
index 0000000..4315b68
--- /dev/null
+++ b/lib/service/git/repo.rs
@@ -0,0 +1,441 @@
+use db::sqlx;
+use git::rpc::{proto as p, proto::init_service_client::InitServiceClient};
+use model::repos::{RepoModel, RepoTopicModel};
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, git::rpc_err, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct RepoResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+    pub description: Option<String>,
+    pub default_branch: String,
+    pub visibility: String,
+    #[schema(value_type = i64)]
+    pub size_bytes: i64,
+    pub is_archived: bool,
+    pub is_template: bool,
+    pub is_mirror: bool,
+    #[schema(value_type = String)]
+    pub created_by: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub(crate) fn repo_response(repo: RepoModel) -> RepoResponse {
+    RepoResponse {
+        id: repo.id,
+        name: repo.name,
+        description: repo.description,
+        default_branch: repo.default_branch,
+        visibility: repo.visibility,
+        size_bytes: repo.size_bytes,
+        is_archived: repo.is_archived,
+        is_template: repo.is_template,
+        is_mirror: repo.is_mirror,
+        created_by: repo.created_by,
+        created_at: repo.created_at,
+        updated_at: repo.updated_at,
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateRepo {
+    pub name: Option<String>,
+    pub description: Option<String>,
+    pub default_branch: Option<String>,
+    pub visibility: Option<String>,
+    pub is_archived: Option<bool>,
+    pub is_template: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct TransferRepo {
+    pub target_workspace: String,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::IntoParams)]
+pub struct RepoFilter {
+    pub visibility: Option<String>,
+    pub is_archived: Option<bool>,
+    pub search: Option<String>,
+}
+
+impl AppService {
+    pub async fn repo_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        filter: RepoFilter,
+        pagination: Pagination,
+    ) -> Result<Vec<RepoResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let mut param_idx = 2;
+        let mut sql = String::from(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at \
+             FROM repo WHERE wk = $1 AND deleted_at IS NULL",
+        );
+
+        if filter.visibility.is_some() {
+            sql.push_str(&format!(" AND visibility = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.is_archived.is_some() {
+            sql.push_str(&format!(" AND is_archived = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.search.is_some() {
+            sql.push_str(&format!(" AND name ILIKE ${param_idx}"));
+            param_idx += 1;
+        }
+
+        let offset_idx = param_idx;
+        let limit_idx = param_idx + 1;
+        sql.push_str(&format!(
+            " ORDER BY name ASC OFFSET ${offset_idx} LIMIT ${limit_idx}"
+        ));
+
+        let mut q = sqlx::query_as::<_, RepoModel>(sqlx::AssertSqlSafe(sql))
+            .bind(wk.id);
+
+        if let Some(vis) = &filter.visibility {
+            q = q.bind(vis.clone());
+        }
+        if let Some(archived) = filter.is_archived {
+            q = q.bind(archived);
+        }
+        if let Some(search) = &filter.search {
+            q = q.bind(format!("%{}%", search));
+        }
+
+        q = q
+            .bind(pagination.offset() as i64)
+            .bind(pagination.limit() as i64);
+
+        let rows = q
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(repo_response).collect())
+    }
+
+    pub async fn repo_get(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<RepoResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        Ok(repo_response(repo))
+    }
+
+    pub async fn repo_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: UpdateRepo,
+    ) -> Result<RepoResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let mut repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let next_name = match params.name {
+            Some(name) => {
+                let name = name.trim();
+                if name.is_empty() {
+                    return Err(AppError::BadRequest(
+                        "repo name is required".to_string(),
+                    ));
+                }
+                if name != repo.name {
+                    let existing = sqlx::query_scalar::<_, bool>(
+                        "SELECT EXISTS(SELECT 1 FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL)",
+                    )
+                    .bind(wk.id)
+                    .bind(name)
+                    .fetch_one(self.db.reader())
+                    .await
+                    .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+                    if existing {
+                        return Err(AppError::RepoNameAlreadyExists);
+                    }
+                    Some(name.to_string())
+                } else {
+                    None
+                }
+            }
+            None => None,
+        };
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        if let Some(next_name) = &next_name {
+            sqlx::query(
+                "INSERT INTO repo_history_name (id, repo, name, changed_by, created_at) \
+                 VALUES ($1, $2, $3, $4, $5)",
+            )
+            .bind(uuid::Uuid::now_v7())
+            .bind(repo.id)
+            .bind(&repo.name)
+            .bind(user_uid)
+            .bind(chrono::Utc::now())
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+            repo.name = next_name.clone();
+        }
+
+        if let Some(desc) = params.description {
+            repo.description = if desc.is_empty() { None } else { Some(desc) };
+        }
+        let mut default_branch_changed = false;
+        if let Some(branch) = params.default_branch {
+            repo.default_branch = branch;
+            default_branch_changed = true;
+        }
+        if let Some(vis) = params.visibility {
+            repo.visibility = vis;
+        }
+        if let Some(archived) = params.is_archived {
+            repo.is_archived = archived;
+        }
+        if let Some(template) = params.is_template {
+            repo.is_template = template;
+        }
+
+        let updated = sqlx::query_as::<_, RepoModel>(
+            "UPDATE repo SET name = $1, description = $2, default_branch = $3, \
+             visibility = $4, is_archived = $5, is_template = $6, updated_at = $7 \
+             WHERE id = $8 \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(&repo.name)
+        .bind(&repo.description)
+        .bind(&repo.default_branch)
+        .bind(&repo.visibility)
+        .bind(repo.is_archived)
+        .bind(repo.is_template)
+        .bind(chrono::Utc::now())
+        .bind(repo.id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        if default_branch_changed {
+            let mut client = InitServiceClient::new(self.git.clone());
+            let _ = client
+                .set_default_branch(tonic::Request::new(
+                    p::SetDefaultBranchRequest {
+                        repo_id: repo.id.to_string(),
+                        branch_name: repo.default_branch.clone(),
+                    },
+                ))
+                .await
+                .map_err(rpc_err);
+            self.queue_sync(repo.id).await;
+        }
+
+        Ok(repo_response(updated))
+    }
+
+    pub async fn repo_archive(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<RepoResponse, AppError> {
+        self.repo_update(
+            ctx,
+            wk_name,
+            repo_name,
+            UpdateRepo {
+                name: None,
+                description: None,
+                default_branch: None,
+                visibility: None,
+                is_archived: Some(true),
+                is_template: None,
+            },
+        )
+        .await
+    }
+
+    pub async fn repo_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_owner(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        sqlx::query("UPDATE repo SET deleted_at = $1 WHERE id = $2")
+            .bind(chrono::Utc::now())
+            .bind(repo.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn repo_transfer(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: TransferRepo,
+    ) -> Result<RepoResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let src_wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_owner(src_wk.id, user_uid).await?;
+        let repo = self.repo_resolve(src_wk.id, repo_name).await?;
+
+        let target_wk =
+            self.workspace_resolve(&params.target_workspace).await?;
+        self.workspace_require_admin(target_wk.id, user_uid).await?;
+
+        let existing = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM repo WHERE wk = $1 AND name = $2 AND deleted_at IS NULL)",
+        )
+        .bind(target_wk.id)
+        .bind(&repo.name)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        if existing {
+            return Err(AppError::Conflict(
+                "repo name already exists in target workspace".to_string(),
+            ));
+        }
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        sqlx::query(
+            "INSERT INTO repo_history_name (id, repo, name, changed_by, created_at) \
+             VALUES ($1, $2, $3, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(repo.id)
+        .bind(&format!("{}/{}", src_wk.name, repo.name))
+        .bind(user_uid)
+        .bind(chrono::Utc::now())
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let updated = sqlx::query_as::<_, RepoModel>(
+            "UPDATE repo SET wk = $1, updated_at = $2 WHERE id = $3 \
+             RETURNING id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at",
+        )
+        .bind(target_wk.id)
+        .bind(chrono::Utc::now())
+        .bind(repo.id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        Ok(repo_response(updated))
+    }
+
+    pub async fn repo_topics(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<Vec<String>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let rows = sqlx::query_as::<_, RepoTopicModel>(
+            "SELECT repo, topic, created_at FROM repo_topic WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(|r| r.topic).collect())
+    }
+
+    pub async fn repo_update_topics(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        topics: Vec<String>,
+    ) -> Result<Vec<String>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        sqlx::query("DELETE FROM repo_topic WHERE repo = $1")
+            .bind(repo.id)
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        for topic in &topics {
+            let topic = topic.trim();
+            if topic.is_empty() {
+                continue;
+            }
+            sqlx::query(
+                "INSERT INTO repo_topic (repo, topic, created_at) VALUES ($1, $2, $3)",
+            )
+            .bind(repo.id)
+            .bind(topic)
+            .bind(chrono::Utc::now())
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        Ok(topics)
+    }
+
+    /// CMDK BFF: list repo names + descriptions for a workspace.
+    pub async fn repo_list_inner(
+        &self,
+        wk_name: &str,
+    ) -> Result<Vec<(String, Option<String>)>, AppError> {
+        let wk = sqlx::query_as::<_, (uuid::Uuid,)>(
+            "SELECT id FROM workspace WHERE name = $1"
+        )
+        .bind(wk_name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("workspace not found".to_string()))?;
+
+        let rows = sqlx::query_as::<_, (String, Option<String>)>(
+            "SELECT name, description FROM repo WHERE wk = $1 AND deleted_at IS NULL ORDER BY updated_at DESC"
+        )
+        .bind(wk.0)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(rows)
+    }
+}
diff --git a/lib/service/git/star.rs b/lib/service/git/star.rs
new file mode 100644
index 0000000..089b034
--- /dev/null
+++ b/lib/service/git/star.rs
@@ -0,0 +1,98 @@
+use db::sqlx;
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+impl AppService {
+    pub async fn git_repo_star(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<serde_json::Value, AppError> {
+        let user_uid = session_user(ctx)?;
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        sqlx::query(
+            "INSERT INTO repo_star (repo, \"user\", created_at) VALUES ($1, $2, $3) \
+             ON CONFLICT (repo, \"user\") DO NOTHING",
+        )
+        .bind(repo.id)
+        .bind(user_uid)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let count: (i64,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM repo_star WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(serde_json::json!({ "starred": true, "count": count.0 }))
+    }
+
+    pub async fn git_repo_unstar(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<serde_json::Value, AppError> {
+        let user_uid = session_user(ctx)?;
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        sqlx::query(
+            "DELETE FROM repo_star WHERE repo = $1 AND \"user\" = $2",
+        )
+        .bind(repo.id)
+        .bind(user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let count: (i64,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM repo_star WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(serde_json::json!({ "starred": false, "count": count.0 }))
+    }
+
+    pub async fn git_repo_star_status(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<serde_json::Value, AppError> {
+        let user_uid = session_user(ctx)?;
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let exists: (bool,) = sqlx::query_as(
+            "SELECT EXISTS(SELECT 1 FROM repo_star WHERE repo = $1 AND \"user\" = $2)",
+        )
+        .bind(repo.id)
+        .bind(user_uid)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let count: (i64,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM repo_star WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(serde_json::json!({
+            "starred": exists.0,
+            "count": count.0,
+        }))
+    }
+}
diff --git a/lib/service/git/tag.rs b/lib/service/git/tag.rs
new file mode 100644
index 0000000..096bae0
--- /dev/null
+++ b/lib/service/git/tag.rs
@@ -0,0 +1,157 @@
+use git::rpc::{proto as p, proto::tag_service_client::TagServiceClient};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_tag_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        pagination: Pagination,
+    ) -> Result<p::TagListResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let mut resp = client
+            .tag_list(tonic::Request::new(p::TagListRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+
+        let offset = pagination.offset() as usize;
+        let limit = pagination.limit() as usize;
+        if offset > 0 || resp.tags.len() > limit {
+            let start = offset.min(resp.tags.len());
+            let end = (start + limit).min(resp.tags.len());
+            resp.tags = resp.tags.drain(start..end).collect();
+        }
+        Ok(resp)
+    }
+
+    pub async fn git_tag_info(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        name: String,
+    ) -> Result<p::TagInfoResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let resp = client
+            .tag_info(tonic::Request::new(p::TagInfoRequest {
+                repo_id: repo.id.to_string(),
+                name,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_tag_summary(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<p::TagSummaryResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let resp = client
+            .tag_summary(tonic::Request::new(p::TagSummaryRequest {
+                repo_id: repo.id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_tag_init(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::TagInitParams,
+    ) -> Result<p::TagInitResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let resp = client
+            .tag_init(tonic::Request::new(p::TagInitRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+
+    pub async fn git_tag_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::TagDeleteParams,
+    ) -> Result<p::TagDeleteResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let resp = client
+            .tag_delete(tonic::Request::new(p::TagDeleteRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+
+    pub async fn git_tag_rename(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::TagRenameParams,
+    ) -> Result<p::TagRenameResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let resp = client
+            .tag_rename(tonic::Request::new(p::TagRenameRequest {
+                repo_id: repo.id.to_string(),
+                params: Some(params),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+
+    pub async fn git_tag_update_message(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: p::TagUpdateMessageParams,
+    ) -> Result<p::TagUpdateMessageResponse, AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        let mut client = TagServiceClient::new(self.git.clone());
+        let resp = client
+            .tag_update_message(tonic::Request::new(
+                p::TagUpdateMessageRequest {
+                    repo_id: repo.id.to_string(),
+                    params: Some(params),
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        self.queue_sync(repo.id).await;
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/tree.rs b/lib/service/git/tree.rs
new file mode 100644
index 0000000..033dbb3
--- /dev/null
+++ b/lib/service/git/tree.rs
@@ -0,0 +1,98 @@
+use git::rpc::{proto as p, proto::tree_service_client::TreeServiceClient};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub async fn git_tree_entries(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+        base_path: String,
+        last: bool,
+    ) -> Result<p::TreeEntriesResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TreeServiceClient::new(self.git.clone());
+        let resp = client
+            .tree_entries(tonic::Request::new(p::TreeEntriesRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: oid }),
+                base_path,
+                last,
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_tree_entry_by_path(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        tree_oid: String,
+        path: String,
+    ) -> Result<p::TreeEntryByPathResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TreeServiceClient::new(self.git.clone());
+        let resp = client
+            .tree_entry_by_path(tonic::Request::new(
+                p::TreeEntryByPathRequest {
+                    repo_id: repo.id.to_string(),
+                    tree_oid: Some(p::ObjectId { value: tree_oid }),
+                    path,
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_tree_entry_by_path_from_commit(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        commit_oid: String,
+        path: String,
+    ) -> Result<p::TreeEntryByPathFromCommitResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TreeServiceClient::new(self.git.clone());
+        let resp = client
+            .tree_entry_by_path_from_commit(tonic::Request::new(
+                p::TreeEntryByPathFromCommitRequest {
+                    repo_id: repo.id.to_string(),
+                    commit_oid: Some(p::ObjectId { value: commit_oid }),
+                    path,
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn git_resolve_tree(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        oid: String,
+    ) -> Result<p::ResolveTreeResponse, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let mut client = TreeServiceClient::new(self.git.clone());
+        let resp = client
+            .resolve_tree(tonic::Request::new(p::ResolveTreeRequest {
+                repo_id: repo.id.to_string(),
+                oid: Some(p::ObjectId { value: oid }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+}
diff --git a/lib/service/git/watch.rs b/lib/service/git/watch.rs
new file mode 100644
index 0000000..b0dd850
--- /dev/null
+++ b/lib/service/git/watch.rs
@@ -0,0 +1,105 @@
+use db::sqlx;
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+impl AppService {
+    pub async fn git_repo_watch(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        level: Option<String>,
+    ) -> Result<serde_json::Value, AppError> {
+        let user_uid = session_user(ctx)?;
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        let level = level.unwrap_or_else(|| "participating".to_string());
+
+        sqlx::query(
+            "INSERT INTO repo_watch (repo, \"user\", \"level\", created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5) \
+             ON CONFLICT (repo, \"user\") DO UPDATE SET level = $3, updated_at = $5",
+        )
+        .bind(repo.id)
+        .bind(user_uid)
+        .bind(&level)
+        .bind(chrono::Utc::now())
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let count: (i64,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM repo_watch WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(serde_json::json!({ "watching": true, "count": count.0, "level": level }))
+    }
+
+    pub async fn git_repo_unwatch(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<serde_json::Value, AppError> {
+        let user_uid = session_user(ctx)?;
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        sqlx::query(
+            "DELETE FROM repo_watch WHERE repo = $1 AND \"user\" = $2",
+        )
+        .bind(repo.id)
+        .bind(user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let count: (i64,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM repo_watch WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(serde_json::json!({ "watching": false, "count": count.0 }))
+    }
+
+    pub async fn git_repo_watch_status(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<serde_json::Value, AppError> {
+        let user_uid = session_user(ctx)?;
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let watch: Option<(bool, String)> = sqlx::query_as(
+            "SELECT EXISTS(SELECT 1 FROM repo_watch WHERE repo = $1 AND \"user\" = $2), \
+             COALESCE((SELECT level FROM repo_watch WHERE repo = $1 AND \"user\" = $2), '')",
+        )
+        .bind(repo.id)
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let count: (i64,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM repo_watch WHERE repo = $1",
+        )
+        .bind(repo.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(serde_json::json!({
+            "watching": watch.as_ref().map(|(w, _)| *w).unwrap_or(false),
+            "count": count.0,
+            "level": watch.map(|(_, l)| l).unwrap_or_default(),
+        }))
+    }
+}
diff --git a/lib/service/git/webhook.rs b/lib/service/git/webhook.rs
new file mode 100644
index 0000000..4cf068c
--- /dev/null
+++ b/lib/service/git/webhook.rs
@@ -0,0 +1,365 @@
+use db::sqlx;
+use hmac::{Hmac, KeyInit, Mac};
+use model::repos::{RepoWebhookDeliveryModel, RepoWebhookModel};
+use serde::{Deserialize, Serialize};
+use session::Session;
+use sha2::Sha256;
+
+use crate::{AppService, Pagination, error::AppError, session_user};
+
+type HmacSha256 = Hmac<Sha256>;
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum WebhookEvent {
+    Push,
+    PushBranch,
+    PushTag,
+    Issue,
+    PullRequest,
+    Comment,
+    Release,
+    Fork,
+    Wiki,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WebhookResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub repo: uuid::Uuid,
+    pub url: String,
+    pub events: Vec<String>,
+    pub active: bool,
+    #[schema(value_type = String)]
+    pub created_by: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub(crate) fn webhook_response(w: RepoWebhookModel) -> WebhookResponse {
+    WebhookResponse {
+        id: w.id,
+        repo: w.repo,
+        url: w.url,
+        events: w
+            .events
+            .split('.')
+            .filter(|s| !s.is_empty())
+            .map(|s| s.to_string())
+            .collect(),
+        active: w.active,
+        created_by: w.created_by,
+        created_at: w.created_at,
+        updated_at: w.updated_at,
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WebhookDeliveryResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    #[schema(value_type = String)]
+    pub webhook: uuid::Uuid,
+    pub event: String,
+    pub response_status: Option<i32>,
+    pub error: Option<String>,
+    #[schema(value_type = Option<String>)]
+    pub delivered_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub(crate) fn delivery_response(
+    d: RepoWebhookDeliveryModel,
+) -> WebhookDeliveryResponse {
+    WebhookDeliveryResponse {
+        id: d.id,
+        webhook: d.webhook,
+        event: d.event,
+        response_status: d.response_status,
+        error: d.error,
+        delivered_at: d.delivered_at,
+        created_at: d.created_at,
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateWebhook {
+    pub url: String,
+    pub secret: Option<String>,
+    pub events: Vec<String>,
+    pub active: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateWebhook {
+    pub url: Option<String>,
+    pub secret: Option<String>,
+    pub events: Option<Vec<String>>,
+    pub active: Option<bool>,
+}
+
+impl AppService {
+    pub async fn repo_webhook_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<WebhookResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let rows = sqlx::query_as::<_, RepoWebhookModel>(
+            "SELECT id, repo, url, secret_hash, events, active, created_by, created_at, updated_at \
+             FROM repo_webhook WHERE repo = $1 \
+             ORDER BY created_at DESC OFFSET $2 LIMIT $3",
+        )
+        .bind(repo.id)
+        .bind(pagination.offset() as i64)
+        .bind(pagination.limit() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(webhook_response).collect())
+    }
+
+    pub async fn repo_webhook_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: CreateWebhook,
+    ) -> Result<WebhookResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let url = params.url.trim();
+        if url.is_empty() {
+            return Err(AppError::BadRequest("url is required".to_string()));
+        }
+
+        let secret_hash = params.secret.map(|s| {
+            let mut mac = HmacSha256::new_from_slice(b"gitdata-webhook-secret")
+                .expect("HMAC can take key of any size");
+            mac.update(s.as_bytes());
+            let result = mac.finalize();
+            let code_bytes = result.into_bytes();
+            hex::encode(code_bytes)
+        });
+
+        let events = params.events.join(".");
+        let active = params.active.unwrap_or(true);
+        let id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+
+        let row = sqlx::query_as::<_, RepoWebhookModel>(
+            "INSERT INTO repo_webhook \
+             (id, repo, url, secret_hash, events, active, created_by, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $8) \
+             RETURNING id, repo, url, secret_hash, events, active, created_by, created_at, updated_at",
+        )
+        .bind(id)
+        .bind(repo.id)
+        .bind(url)
+        .bind(&secret_hash)
+        .bind(&events)
+        .bind(active)
+        .bind(user_uid)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(webhook_response(row))
+    }
+
+    pub async fn repo_webhook_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        webhook_id: uuid::Uuid,
+        params: UpdateWebhook,
+    ) -> Result<WebhookResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let existing = sqlx::query_as::<_, RepoWebhookModel>(
+            "SELECT id, repo, url, secret_hash, events, active, created_by, created_at, updated_at \
+             FROM repo_webhook WHERE id = $1 AND repo = $2",
+        )
+        .bind(webhook_id)
+        .bind(repo.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("webhook not found".to_string()))?;
+
+        let url = params.url.unwrap_or(existing.url);
+        let events = params
+            .events
+            .map(|e| e.join("."))
+            .unwrap_or(existing.events);
+        let active = params.active.unwrap_or(existing.active);
+
+        let secret_hash = if let Some(secret) = params.secret {
+            let mut mac = HmacSha256::new_from_slice(b"gitdata-webhook-secret")
+                .expect("HMAC can take key of any size");
+            mac.update(secret.as_bytes());
+            let result = mac.finalize();
+            let code_bytes = result.into_bytes();
+            Some(hex::encode(code_bytes))
+        } else {
+            existing.secret_hash
+        };
+
+        let row = sqlx::query_as::<_, RepoWebhookModel>(
+            "UPDATE repo_webhook SET url = $1, secret_hash = $2, events = $3, \
+             active = $4, updated_at = $5 WHERE id = $6 \
+             RETURNING id, repo, url, secret_hash, events, active, created_by, created_at, updated_at",
+        )
+        .bind(&url)
+        .bind(&secret_hash)
+        .bind(&events)
+        .bind(active)
+        .bind(chrono::Utc::now())
+        .bind(webhook_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(webhook_response(row))
+    }
+
+    pub async fn repo_webhook_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        webhook_id: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let result =
+            sqlx::query("DELETE FROM repo_webhook WHERE id = $1 AND repo = $2")
+                .bind(webhook_id)
+                .bind(repo.id)
+                .execute(self.db.writer())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if result.rows_affected() == 0 {
+            return Err(AppError::NotFound("webhook not found".to_string()));
+        }
+
+        Ok(())
+    }
+
+    pub async fn repo_webhook_deliveries(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        webhook_id: uuid::Uuid,
+        pagination: Pagination,
+    ) -> Result<Vec<WebhookDeliveryResponse>, AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+
+        let rows = sqlx::query_as::<_, RepoWebhookDeliveryModel>(
+            "SELECT id, repo, webhook, event, request_headers, request_body, \
+             response_status, response_headers, response_body, error, delivered_at, created_at \
+             FROM repo_webhook_delivery WHERE webhook = $1 AND repo = $2 \
+             ORDER BY created_at DESC OFFSET $3 LIMIT $4",
+        )
+        .bind(webhook_id)
+        .bind(repo.id)
+        .bind(pagination.offset() as i64)
+        .bind(pagination.limit() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(delivery_response).collect())
+    }
+    pub async fn trigger_webhook_event(
+        &self,
+        repo_id: uuid::Uuid,
+        event: &str,
+        payload: serde_json::Value,
+    ) -> Result<(), AppError> {
+        let webhooks = sqlx::query_as::<_, RepoWebhookModel>(
+            "SELECT id, repo, url, secret_hash, events, active, created_by, created_at, updated_at \
+             FROM repo_webhook WHERE repo = $1 AND active = true",
+        )
+        .bind(repo_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        for wh in webhooks {
+            let subscribed_events: Vec<&str> =
+                wh.events.split('.').filter(|s| !s.is_empty()).collect();
+            let matches = subscribed_events.iter().any(|e| {
+                *e == event
+                    || *e == "push"
+                        && (event == "push_branch" || event == "push_tag")
+            });
+
+            if !matches {
+                continue;
+            }
+
+            let delivery_id = uuid::Uuid::now_v7();
+            let now = chrono::Utc::now();
+            sqlx::query(
+                "INSERT INTO repo_webhook_delivery \
+                 (id, repo, webhook, event, request_headers, request_body, \
+                  response_status, response_headers, response_body, error, delivered_at, created_at) \
+                 VALUES ($1, $2, $3, $4, NULL, NULL, NULL, NULL, NULL, NULL, NULL, $5)",
+            )
+            .bind(delivery_id)
+            .bind(repo_id)
+            .bind(wh.id)
+            .bind(event)
+            .bind(now)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+            let task = git::sync::webhook::WebhookDeliveryTask {
+                id: delivery_id.to_string(),
+                webhook_id: wh.id.to_string(),
+                repo_id: repo_id.to_string(),
+                event: event.to_string(),
+                url: wh.url.clone(),
+                secret: wh.secret_hash.clone(),
+                payload: payload.clone(),
+                created_at: now,
+                retry_count: 0,
+            };
+
+            if let Err(e) =
+                git::sync::webhook::enqueue_delivery(task, &self.redis_pool)
+                    .await
+            {
+                tracing::error!(
+                    repo_id = %repo_id,
+                    webhook_id = %wh.id,
+                    error = %e,
+                    "failed to enqueue webhook delivery"
+                );
+            }
+        }
+
+        Ok(())
+    }
+}
diff --git a/lib/service/issues/assignee.rs b/lib/service/issues/assignee.rs
new file mode 100644
index 0000000..7898b18
--- /dev/null
+++ b/lib/service/issues/assignee.rs
@@ -0,0 +1,118 @@
+use db::sqlx;
+use model::users::UserModel;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{IssueAuthor, issue_author};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AssignIssueUser {
+    pub username: String,
+}
+
+impl AppService {
+    pub async fn issue_assign(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: AssignIssueUser,
+    ) -> Result<Vec<IssueAuthor>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+        let target = self
+            .users_find_active_user_by_username(&params.username)
+            .await?;
+        self.workspace_require_member(wk.id, target.id).await?;
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO issue_assignee (issue, \"user\", assigned_by, created_at) \
+             VALUES ($1, $2, $3, $4) \
+             ON CONFLICT (issue, \"user\") DO NOTHING",
+        )
+        .bind(issue.id)
+        .bind(target.id)
+        .bind(user_uid)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'assigned', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&params.username)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_assignees(issue.id).await
+    }
+
+    pub async fn issue_unassign(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        username: &str,
+    ) -> Result<Vec<IssueAuthor>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+        let target = self.users_find_active_user_by_username(username).await?;
+
+        sqlx::query(
+            "DELETE FROM issue_assignee WHERE issue = $1 AND \"user\" = $2",
+        )
+        .bind(issue.id)
+        .bind(target.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'unassigned', $4, NULL, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(username)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_assignees(issue.id).await
+    }
+
+    pub(crate) async fn issue_assignees(
+        &self,
+        issue_id: uuid::Uuid,
+    ) -> Result<Vec<IssueAuthor>, AppError> {
+        let rows = sqlx::query_as::<_, UserModel>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+             u.last_sign_in_at, u.created_at, u.updated_at \
+             FROM issue_assignee ia \
+             INNER JOIN \"user\" u ON u.id = ia.\"user\" \
+             WHERE ia.issue = $1 AND u.allow_use = true \
+             ORDER BY ia.created_at ASC",
+        )
+        .bind(issue_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(issue_author).collect())
+    }
+}
diff --git a/lib/service/issues/binding.rs b/lib/service/issues/binding.rs
new file mode 100644
index 0000000..88529a1
--- /dev/null
+++ b/lib/service/issues/binding.rs
@@ -0,0 +1,261 @@
+use db::sqlx;
+use model::{pull_request::PullRequestModel, repos::RepoModel};
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{
+    IssuePullRequestResponse, IssueRepoResponse, issue_pr_response,
+    issue_repo_response,
+};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct BindIssueRepo {
+    pub repo_id: uuid::Uuid,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct BindIssuePullRequest {
+    pub pull_request_id: uuid::Uuid,
+}
+
+impl AppService {
+    pub async fn issue_bind_repo(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: BindIssueRepo,
+    ) -> Result<Vec<IssueRepoResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let repo = sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at \
+             FROM repo WHERE id = $1 AND wk = $2 AND deleted_at IS NULL",
+        )
+        .bind(params.repo_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::RepoNotFound)?;
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO issue_repo (issue, repo, created_at) VALUES ($1, $2, $3) \
+             ON CONFLICT (issue, repo) DO NOTHING",
+        )
+        .bind(issue.id)
+        .bind(repo.id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'linked_repo', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&repo.name)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_repos(issue.id).await
+    }
+
+    pub async fn issue_unbind_repo(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        repo_id: uuid::Uuid,
+    ) -> Result<Vec<IssueRepoResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let repo = sqlx::query_as::<_, RepoModel>(
+            "SELECT id, wk, name, description, default_branch, visibility, size_bytes, \
+             is_archived, is_template, is_mirror, created_by, storage_path, created_at, updated_at, deleted_at \
+             FROM repo WHERE id = $1 AND wk = $2",
+        )
+        .bind(repo_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::RepoNotFound)?;
+
+        sqlx::query("DELETE FROM issue_repo WHERE issue = $1 AND repo = $2")
+            .bind(issue.id)
+            .bind(repo_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'unlinked_repo', $4, NULL, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&repo.name)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_repos(issue.id).await
+    }
+
+    pub async fn issue_bind_pull_request(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: BindIssuePullRequest,
+    ) -> Result<Vec<IssuePullRequestResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let pr = sqlx::query_as::<_, PullRequestModel>(
+            "SELECT id, repo, number, title, body, state, draft, author, \
+             source_repo, source_branch, source_sha, target_branch, target_sha, \
+             merged_by, merged_at, closed_by, closed_at, created_at, updated_at, deleted_at \
+             FROM pull_request WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(params.pull_request_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::PullRequestNotFound)?;
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO issue_pull_request (issue, pull_request, created_at) VALUES ($1, $2, $3) \
+             ON CONFLICT (issue, pull_request) DO NOTHING",
+        )
+        .bind(issue.id)
+        .bind(pr.id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'linked_pull_request', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(format!("#{}", pr.number))
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_pull_requests(issue.id).await
+    }
+
+    pub async fn issue_unbind_pull_request(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        pull_request_id: uuid::Uuid,
+    ) -> Result<Vec<IssuePullRequestResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let pr = sqlx::query_as::<_, PullRequestModel>(
+            "SELECT id, repo, number, title, body, state, draft, author, \
+             source_repo, source_branch, source_sha, target_branch, target_sha, \
+             merged_by, merged_at, closed_by, closed_at, created_at, updated_at, deleted_at \
+             FROM pull_request WHERE id = $1",
+        )
+        .bind(pull_request_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::PullRequestNotFound)?;
+
+        sqlx::query("DELETE FROM issue_pull_request WHERE issue = $1 AND pull_request = $2")
+            .bind(issue.id)
+            .bind(pull_request_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'unlinked_pull_request', $4, NULL, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(format!("#{}", pr.number))
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_pull_requests(issue.id).await
+    }
+
+    pub(crate) async fn issue_repos(
+        &self,
+        issue_id: uuid::Uuid,
+    ) -> Result<Vec<IssueRepoResponse>, AppError> {
+        let repos = sqlx::query_as::<_, RepoModel>(
+            "SELECT r.id, r.wk, r.name, r.description, r.default_branch, r.visibility, r.size_bytes, \
+             r.is_archived, r.is_template, r.is_mirror, r.created_by, r.storage_path, r.created_at, r.updated_at, r.deleted_at \
+             FROM issue_repo ir \
+             INNER JOIN repo r ON r.id = ir.repo \
+             WHERE ir.issue = $1 AND r.deleted_at IS NULL \
+             ORDER BY r.name ASC",
+        )
+        .bind(issue_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(repos.into_iter().map(issue_repo_response).collect())
+    }
+
+    pub(crate) async fn issue_pull_requests(
+        &self,
+        issue_id: uuid::Uuid,
+    ) -> Result<Vec<IssuePullRequestResponse>, AppError> {
+        let prs = sqlx::query_as::<_, PullRequestModel>(
+            "SELECT pr.id, pr.repo, pr.number, pr.title, pr.body, pr.state, pr.draft, pr.author, \
+             pr.source_repo, pr.source_branch, pr.source_sha, pr.target_branch, pr.target_sha, \
+             pr.merged_by, pr.merged_at, pr.closed_by, pr.closed_at, pr.created_at, pr.updated_at, pr.deleted_at \
+             FROM issue_pull_request ip \
+             INNER JOIN pull_request pr ON pr.id = ip.pull_request \
+             WHERE ip.issue = $1 AND pr.deleted_at IS NULL \
+             ORDER BY pr.created_at DESC",
+        )
+        .bind(issue_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(prs.into_iter().map(issue_pr_response).collect())
+    }
+}
diff --git a/lib/service/issues/comment.rs b/lib/service/issues/comment.rs
new file mode 100644
index 0000000..2808aa6
--- /dev/null
+++ b/lib/service/issues/comment.rs
@@ -0,0 +1,209 @@
+use db::sqlx;
+use model::issues::IssueCommentModel;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{IssueCommentResponse, issue_author};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateComment {
+    pub body: String,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateComment {
+    pub body: String,
+}
+
+impl AppService {
+    pub async fn issue_comment_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: CreateComment,
+    ) -> Result<IssueCommentResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let body = params.body.trim();
+        if body.is_empty() {
+            return Err(AppError::BadRequest(
+                "comment body is required".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let id = uuid::Uuid::now_v7();
+
+        let comment = sqlx::query_as::<_, IssueCommentModel>(
+            "INSERT INTO issue_comment (id, issue, author, body, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $5) \
+             RETURNING id, issue, author, body, created_at, updated_at, deleted_at",
+        )
+        .bind(id)
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(body)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'commented', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(comment.id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let author = self.users_find_by_id(user_uid).await?;
+        Ok(IssueCommentResponse {
+            id: comment.id,
+            author: issue_author(author),
+            body: comment.body,
+            created_at: comment.created_at,
+            updated_at: comment.updated_at,
+        })
+    }
+
+    pub async fn issue_comment_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<Vec<IssueCommentResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let comments = sqlx::query_as::<_, IssueCommentModel>(
+            "SELECT id, issue, author, body, created_at, updated_at, deleted_at \
+             FROM issue_comment WHERE issue = $1 AND deleted_at IS NULL \
+             ORDER BY created_at ASC",
+        )
+        .bind(issue.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for comment in comments {
+            let author = self.users_find_by_id(comment.author).await?;
+            results.push(IssueCommentResponse {
+                id: comment.id,
+                author: issue_author(author),
+                body: comment.body,
+                created_at: comment.created_at,
+                updated_at: comment.updated_at,
+            });
+        }
+        Ok(results)
+    }
+
+    pub async fn issue_comment_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        comment_id: uuid::Uuid,
+        params: UpdateComment,
+    ) -> Result<IssueCommentResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let comment = sqlx::query_as::<_, IssueCommentModel>(
+            "SELECT id, issue, author, body, created_at, updated_at, deleted_at \
+             FROM issue_comment WHERE id = $1 AND issue = $2 AND deleted_at IS NULL",
+        )
+        .bind(comment_id)
+        .bind(issue.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::CommentNotFound)?;
+
+        if comment.author != user_uid {
+            return Err(AppError::Forbidden(
+                "only the comment author can edit".to_string(),
+            ));
+        }
+
+        let body = params.body.trim();
+        if body.is_empty() {
+            return Err(AppError::BadRequest(
+                "comment body is required".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let updated = sqlx::query_as::<_, IssueCommentModel>(
+            "UPDATE issue_comment SET body = $1, updated_at = $2 WHERE id = $3 \
+             RETURNING id, issue, author, body, created_at, updated_at, deleted_at",
+        )
+        .bind(body)
+        .bind(now)
+        .bind(comment_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let author = self.users_find_by_id(user_uid).await?;
+        Ok(IssueCommentResponse {
+            id: updated.id,
+            author: issue_author(author),
+            body: updated.body,
+            created_at: updated.created_at,
+            updated_at: updated.updated_at,
+        })
+    }
+
+    pub async fn issue_comment_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        comment_id: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let comment = sqlx::query_as::<_, IssueCommentModel>(
+            "SELECT id, issue, author, body, created_at, updated_at, deleted_at \
+             FROM issue_comment WHERE id = $1 AND issue = $2 AND deleted_at IS NULL",
+        )
+        .bind(comment_id)
+        .bind(issue.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::CommentNotFound)?;
+
+        if comment.author != user_uid {
+            self.workspace_require_admin(wk.id, user_uid).await?;
+        }
+
+        sqlx::query("UPDATE issue_comment SET deleted_at = $1 WHERE id = $2")
+            .bind(chrono::Utc::now())
+            .bind(comment_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+}
diff --git a/lib/service/issues/event.rs b/lib/service/issues/event.rs
new file mode 100644
index 0000000..72b421b
--- /dev/null
+++ b/lib/service/issues/event.rs
@@ -0,0 +1,48 @@
+use db::sqlx;
+use model::issues::IssueEventModel;
+use session::Session;
+
+use super::types::{IssueEventResponse, issue_author};
+use crate::{AppService, error::AppError, session_user};
+
+impl AppService {
+    pub async fn issue_events(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<Vec<IssueEventResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let events = sqlx::query_as::<_, IssueEventModel>(
+            "SELECT id, issue, actor, event, from_value, to_value, metadata, created_at \
+             FROM issue_event WHERE issue = $1 \
+             ORDER BY created_at ASC",
+        )
+        .bind(issue.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for event in events {
+            let actor = if let Some(actor_uid) = event.actor {
+                let user = self.users_find_by_id(actor_uid).await.ok();
+                user.map(issue_author)
+            } else {
+                None
+            };
+            results.push(IssueEventResponse {
+                actor,
+                event: event.event,
+                from_value: event.from_value,
+                to_value: event.to_value,
+                created_at: event.created_at,
+            });
+        }
+        Ok(results)
+    }
+}
diff --git a/lib/service/issues/issue.rs b/lib/service/issues/issue.rs
new file mode 100644
index 0000000..b82e96e
--- /dev/null
+++ b/lib/service/issues/issue.rs
@@ -0,0 +1,501 @@
+use db::{sqlx, sqlx::AssertSqlSafe};
+use model::{issues::IssueModel, users::UserModel};
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{IssueFilter, IssueResponse, issue_author};
+use crate::{AppService, Pagination, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateIssue {
+    pub title: String,
+    pub body: Option<String>,
+    pub priority: Option<String>,
+    pub due_at: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateIssue {
+    pub title: Option<String>,
+    pub body: Option<String>,
+    pub priority: Option<String>,
+    pub due_at: Option<String>,
+}
+
+impl AppService {
+    pub async fn issue_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        params: CreateIssue,
+    ) -> Result<IssueResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let title = params.title.trim();
+        if title.is_empty() {
+            return Err(AppError::BadRequest(
+                "issue title is required".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let id = uuid::Uuid::now_v7();
+        let priority = params.priority.unwrap_or_else(|| "normal".to_string());
+        let due_at = params.due_at.and_then(|d| {
+            chrono::DateTime::parse_from_rfc3339(&d)
+                .ok()
+                .map(|dt| dt.to_utc())
+        });
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let issue = sqlx::query_as::<_, IssueModel>(
+            "INSERT INTO issue (id, wk, number, title, body, state, priority, author, due_at, created_at, updated_at) \
+             VALUES ($1, $2, (SELECT COALESCE(MAX(number), 0) + 1 FROM issue WHERE wk = $2 AND deleted_at IS NULL), \
+             $3, $4, 'open', $5, $6, $7, $8, $8) \
+             RETURNING id, wk, number, title, body, state, priority, author, closed_by, closed_at, due_at, created_at, updated_at, deleted_at",
+        )
+        .bind(id)
+        .bind(wk.id)
+        .bind(title)
+        .bind(&params.body)
+        .bind(&priority)
+        .bind(user_uid)
+        .bind(due_at)
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'created', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&issue.title)
+        .bind(now)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+
+        let author = self.users_find_by_id(user_uid).await?;
+        Ok(IssueResponse {
+            number: issue.number,
+            title: issue.title,
+            body: issue.body,
+            state: issue.state,
+            priority: issue.priority,
+            due_at: issue.due_at,
+            author: issue_author(author),
+            closed_by: None,
+            closed_at: None,
+            created_at: issue.created_at,
+            updated_at: issue.updated_at,
+            labels: Vec::new(),
+            assignees: Vec::new(),
+            milestone: None,
+            repos: Vec::new(),
+            pull_requests: Vec::new(),
+        })
+    }
+
+    pub async fn issue_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        filter: IssueFilter,
+        pagination: Pagination,
+    ) -> Result<Vec<IssueResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let mut conditions =
+            vec!["i.wk = $1".to_string(), "i.deleted_at IS NULL".to_string()];
+        let mut param_idx = 2;
+
+        if filter.state.is_some() {
+            conditions.push(format!("i.state = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.priority.is_some() {
+            conditions.push(format!("i.priority = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.label.is_some() {
+            conditions.push(format!(
+                "EXISTS(SELECT 1 FROM issue_label il INNER JOIN label l ON l.id = il.label WHERE il.issue = i.id AND l.name = ${param_idx})"
+            ));
+            param_idx += 1;
+        }
+        if filter.milestone.is_some() {
+            conditions.push(format!(
+                "EXISTS(SELECT 1 FROM issue_milestone im INNER JOIN milestone m ON m.id = im.milestone WHERE im.issue = i.id AND m.title = ${param_idx})"
+            ));
+            param_idx += 1;
+        }
+        if filter.assignee.is_some() {
+            conditions.push(format!(
+                "EXISTS(SELECT 1 FROM issue_assignee ia INNER JOIN \"user\" u ON u.id = ia.\"user\" WHERE ia.issue = i.id AND u.username = ${param_idx})"
+            ));
+            param_idx += 1;
+        }
+
+        let where_clause = conditions.join(" AND ");
+        let limit_idx = param_idx;
+        let offset_idx = param_idx + 1;
+
+        let query = format!(
+            "SELECT i.id, i.wk, i.number, i.title, i.body, i.state, i.priority, i.author, \
+             i.closed_by, i.closed_at, i.due_at, i.created_at, i.updated_at, i.deleted_at \
+             FROM issue i WHERE {where_clause} \
+             ORDER BY i.created_at DESC LIMIT ${limit_idx} OFFSET ${offset_idx}"
+        );
+
+        let mut q =
+            sqlx::query_as::<_, IssueModel>(AssertSqlSafe(query)).bind(wk.id);
+        if let Some(state) = &filter.state {
+            q = q.bind(state);
+        }
+        if let Some(priority) = &filter.priority {
+            q = q.bind(priority);
+        }
+        if let Some(label_name) = &filter.label {
+            q = q.bind(label_name);
+        }
+        if let Some(milestone_title) = &filter.milestone {
+            q = q.bind(milestone_title);
+        }
+        if let Some(assignee_username) = &filter.assignee {
+            q = q.bind(assignee_username);
+        }
+        q = q
+            .bind(pagination.limit() as i64)
+            .bind(pagination.offset() as i64);
+
+        let issues = q
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for issue in issues {
+            results.push(self.issue_build_response(issue).await?);
+        }
+        Ok(results)
+    }
+
+    pub async fn issue_get(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<IssueResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let issue = self.issue_resolve(wk.id, number).await?;
+        self.issue_build_response(issue).await
+    }
+
+    pub async fn issue_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: UpdateIssue,
+    ) -> Result<IssueResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let mut issue = self.issue_resolve(wk.id, number).await?;
+
+        let now = chrono::Utc::now();
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        if let Some(title) = &params.title {
+            let title = title.trim();
+            if title.is_empty() {
+                return Err(AppError::BadRequest(
+                    "issue title is required".to_string(),
+                ));
+            }
+            if title != &issue.title {
+                sqlx::query(
+                    "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+                     VALUES ($1, $2, $3, 'title_changed', $4, $5, $6)",
+                )
+                .bind(uuid::Uuid::now_v7())
+                .bind(issue.id)
+                .bind(user_uid)
+                .bind(&issue.title)
+                .bind(title)
+                .bind(now)
+                .execute(&mut **txn.inner_mut())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+                issue.title = title.to_string();
+            }
+        }
+
+        if let Some(priority) = &params.priority {
+            if priority != &issue.priority {
+                sqlx::query(
+                    "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+                     VALUES ($1, $2, $3, 'priority_changed', $4, $5, $6)",
+                )
+                .bind(uuid::Uuid::now_v7())
+                .bind(issue.id)
+                .bind(user_uid)
+                .bind(&issue.priority)
+                .bind(priority)
+                .bind(now)
+                .execute(&mut **txn.inner_mut())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+                issue.priority = priority.to_string();
+            }
+        }
+
+        let next_body = params.body.map(Some).unwrap_or(issue.body.clone());
+        let next_due_at = params
+            .due_at
+            .and_then(|d| {
+                chrono::DateTime::parse_from_rfc3339(&d)
+                    .ok()
+                    .map(|dt| dt.to_utc())
+            })
+            .or(issue.due_at);
+
+        issue = sqlx::query_as::<_, IssueModel>(
+            "UPDATE issue SET title = $1, body = $2, priority = $3, due_at = $4, updated_at = $5 WHERE id = $6 \
+             RETURNING id, wk, number, title, body, state, priority, author, closed_by, closed_at, due_at, created_at, updated_at, deleted_at",
+        )
+        .bind(&issue.title)
+        .bind(&next_body)
+        .bind(&issue.priority)
+        .bind(next_due_at)
+        .bind(now)
+        .bind(issue.id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        self.issue_build_response(issue).await
+    }
+
+    pub async fn issue_close(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<IssueResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        if issue.state == "closed" {
+            return Err(AppError::BadRequest(
+                "issue is already closed".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "UPDATE issue SET state = 'closed', closed_by = $1, closed_at = $2, updated_at = $2 WHERE id = $3",
+        )
+        .bind(user_uid)
+        .bind(now)
+        .bind(issue.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'closed', $4, 'closed', $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&issue.state)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let issue = self.issue_resolve(wk.id, number).await?;
+        self.issue_build_response(issue).await
+    }
+
+    pub async fn issue_reopen(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<IssueResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        if issue.state == "open" {
+            return Err(AppError::BadRequest(
+                "issue is already open".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "UPDATE issue SET state = 'open', closed_by = NULL, closed_at = NULL, updated_at = $1 WHERE id = $2",
+        )
+        .bind(now)
+        .bind(issue.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'reopened', $4, 'open', $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&issue.state)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let issue = self.issue_resolve(wk.id, number).await?;
+        self.issue_build_response(issue).await
+    }
+
+    pub async fn issue_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        sqlx::query("UPDATE issue SET deleted_at = $1 WHERE id = $2")
+            .bind(chrono::Utc::now())
+            .bind(issue.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub(crate) async fn issue_resolve(
+        &self,
+        wk_id: uuid::Uuid,
+        number: i64,
+    ) -> Result<IssueModel, AppError> {
+        sqlx::query_as::<_, IssueModel>(
+            "SELECT id, wk, number, title, body, state, priority, author, closed_by, closed_at, due_at, \
+             created_at, updated_at, deleted_at \
+             FROM issue WHERE wk = $1 AND number = $2 AND deleted_at IS NULL",
+        )
+        .bind(wk_id)
+        .bind(number)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::IssueNotFound)
+    }
+
+    async fn issue_build_response(
+        &self,
+        issue: IssueModel,
+    ) -> Result<IssueResponse, AppError> {
+        let author = self.users_find_by_id(issue.author).await?;
+
+        let closed_by = if let Some(closed_uid) = issue.closed_by {
+            let user = self.users_find_by_id(closed_uid).await?;
+            Some(issue_author(user))
+        } else {
+            None
+        };
+
+        let labels = self.issue_labels(issue.id).await?;
+        let assignees = self.issue_assignees(issue.id).await?;
+        let milestone = self.issue_milestone(issue.id).await?;
+        let repos = self.issue_repos(issue.id).await?;
+        let pull_requests = self.issue_pull_requests(issue.id).await?;
+
+        Ok(IssueResponse {
+            number: issue.number,
+            title: issue.title,
+            body: issue.body,
+            state: issue.state,
+            priority: issue.priority,
+            due_at: issue.due_at,
+            author: issue_author(author),
+            closed_by,
+            closed_at: issue.closed_at,
+            created_at: issue.created_at,
+            updated_at: issue.updated_at,
+            labels,
+            assignees,
+            milestone,
+            repos,
+            pull_requests,
+        })
+    }
+
+    pub(crate) async fn users_find_by_id(
+        &self,
+        uid: uuid::Uuid,
+    ) -> Result<UserModel, AppError> {
+        sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+             last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE id = $1 AND allow_use = true",
+        )
+        .bind(uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)
+    }
+
+    /// CMDK BFF: list issue numbers, titles, states for a workspace.
+    pub async fn issue_list_inner(
+        &self,
+        wk_name: &str,
+    ) -> Result<Vec<(i32, String, String)>, AppError> {
+        let wk = sqlx::query_as::<_, (uuid::Uuid,)>(
+            "SELECT id FROM workspace WHERE name = $1"
+        )
+        .bind(wk_name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("workspace not found".to_string()))?;
+
+        let rows = sqlx::query_as::<_, (i32, String, String)>(
+            "SELECT number, title, state FROM issue WHERE wk = $1 AND deleted_at IS NULL ORDER BY updated_at DESC LIMIT 50"
+        )
+        .bind(wk.0)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(rows)
+    }
+}
diff --git a/lib/service/issues/label.rs b/lib/service/issues/label.rs
new file mode 100644
index 0000000..e6fb740
--- /dev/null
+++ b/lib/service/issues/label.rs
@@ -0,0 +1,286 @@
+use db::sqlx;
+use model::issues::LabelModel;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{LabelResponse, label_response};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateLabel {
+    pub name: String,
+    pub color: String,
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateLabel {
+    pub name: Option<String>,
+    pub color: Option<String>,
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AddIssueLabel {
+    pub label_id: uuid::Uuid,
+}
+
+impl AppService {
+    pub async fn label_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        params: CreateLabel,
+    ) -> Result<LabelResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let name = params.name.trim();
+        if name.is_empty() {
+            return Err(AppError::BadRequest(
+                "label name is required".to_string(),
+            ));
+        }
+
+        let id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+
+        let label = sqlx::query_as::<_, LabelModel>(
+            "INSERT INTO label (id, wk, name, color, description, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $6) \
+             RETURNING id, wk, name, color, description, created_at, updated_at",
+        )
+        .bind(id)
+        .bind(wk.id)
+        .bind(name)
+        .bind(&params.color)
+        .bind(&params.description)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(label_response(label))
+    }
+
+    pub async fn label_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let labels = sqlx::query_as::<_, LabelModel>(
+            "SELECT id, wk, name, color, description, created_at, updated_at \
+             FROM label WHERE wk = $1 ORDER BY name ASC",
+        )
+        .bind(wk.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(labels.into_iter().map(label_response).collect())
+    }
+
+    pub async fn label_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        label_id: uuid::Uuid,
+        params: UpdateLabel,
+    ) -> Result<LabelResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let label = sqlx::query_as::<_, LabelModel>(
+            "SELECT id, wk, name, color, description, created_at, updated_at \
+             FROM label WHERE id = $1 AND wk = $2",
+        )
+        .bind(label_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::LabelNotFound)?;
+
+        let name = params.name.unwrap_or_else(|| label.name.clone());
+        let color = params.color.unwrap_or_else(|| label.color.clone());
+        let description = params
+            .description
+            .unwrap_or_else(|| label.description.clone().unwrap_or_default());
+
+        let now = chrono::Utc::now();
+        let updated = sqlx::query_as::<_, LabelModel>(
+            "UPDATE label SET name = $1, color = $2, description = $3, updated_at = $4 WHERE id = $5 \
+             RETURNING id, wk, name, color, description, created_at, updated_at",
+        )
+        .bind(name)
+        .bind(color)
+        .bind(description)
+        .bind(now)
+        .bind(label_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(label_response(updated))
+    }
+
+    pub async fn label_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        label_id: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let exists = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM label WHERE id = $1 AND wk = $2)",
+        )
+        .bind(label_id)
+        .bind(wk.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if !exists {
+            return Err(AppError::LabelNotFound);
+        }
+
+        sqlx::query("DELETE FROM issue_label WHERE label = $1")
+            .bind(label_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query("DELETE FROM label WHERE id = $1")
+            .bind(label_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn issue_add_label(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: AddIssueLabel,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let label = sqlx::query_as::<_, LabelModel>(
+            "SELECT id, wk, name, color, description, created_at, updated_at \
+             FROM label WHERE id = $1 AND wk = $2",
+        )
+        .bind(params.label_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::LabelNotFound)?;
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO issue_label (issue, label, created_at) VALUES ($1, $2, $3) \
+             ON CONFLICT (issue, label) DO NOTHING",
+        )
+        .bind(issue.id)
+        .bind(label.id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'labeled', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&label.name)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_labels(issue.id).await
+    }
+
+    pub async fn issue_remove_label(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        label_id: uuid::Uuid,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let label = sqlx::query_as::<_, LabelModel>(
+            "SELECT id, wk, name, color, description, created_at, updated_at \
+             FROM label WHERE id = $1 AND wk = $2",
+        )
+        .bind(label_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::LabelNotFound)?;
+
+        sqlx::query("DELETE FROM issue_label WHERE issue = $1 AND label = $2")
+            .bind(issue.id)
+            .bind(label_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'unlabeled', $4, NULL, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&label.name)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_labels(issue.id).await
+    }
+
+    pub(crate) async fn issue_labels(
+        &self,
+        issue_id: uuid::Uuid,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let labels = sqlx::query_as::<_, LabelModel>(
+            "SELECT l.id, l.wk, l.name, l.color, l.description, l.created_at, l.updated_at \
+             FROM issue_label il \
+             INNER JOIN label l ON l.id = il.label \
+             WHERE il.issue = $1 \
+             ORDER BY l.name ASC",
+        )
+        .bind(issue_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(labels.into_iter().map(label_response).collect())
+    }
+}
diff --git a/lib/service/issues/milestone.rs b/lib/service/issues/milestone.rs
new file mode 100644
index 0000000..d5d7ab9
--- /dev/null
+++ b/lib/service/issues/milestone.rs
@@ -0,0 +1,302 @@
+use db::sqlx;
+use model::issues::MilestoneModel;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{MilestoneResponse, milestone_response};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateMilestone {
+    pub title: String,
+    pub description: Option<String>,
+    pub due_at: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateMilestone {
+    pub title: Option<String>,
+    pub description: Option<String>,
+    pub state: Option<String>,
+    pub due_at: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct SetIssueMilestone {
+    pub milestone_id: uuid::Uuid,
+}
+
+impl AppService {
+    pub async fn milestone_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        params: CreateMilestone,
+    ) -> Result<MilestoneResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let title = params.title.trim();
+        if title.is_empty() {
+            return Err(AppError::BadRequest(
+                "milestone title is required".to_string(),
+            ));
+        }
+
+        let id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+        let due_at = params.due_at.and_then(|d| {
+            chrono::DateTime::parse_from_rfc3339(&d)
+                .ok()
+                .map(|dt| dt.to_utc())
+        });
+
+        let milestone = sqlx::query_as::<_, MilestoneModel>(
+            "INSERT INTO milestone (id, wk, title, description, state, due_at, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, 'open', $5, $6, $6) \
+             RETURNING id, wk, title, description, state, due_at, closed_at, created_at, updated_at",
+        )
+        .bind(id)
+        .bind(wk.id)
+        .bind(title)
+        .bind(&params.description)
+        .bind(due_at)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(milestone_response(milestone))
+    }
+
+    pub async fn milestone_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+    ) -> Result<Vec<MilestoneResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let milestones = sqlx::query_as::<_, MilestoneModel>(
+            "SELECT id, wk, title, description, state, due_at, closed_at, created_at, updated_at \
+             FROM milestone WHERE wk = $1 ORDER BY created_at ASC",
+        )
+        .bind(wk.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(milestones.into_iter().map(milestone_response).collect())
+    }
+
+    pub async fn milestone_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        milestone_id: uuid::Uuid,
+        params: UpdateMilestone,
+    ) -> Result<MilestoneResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let milestone = sqlx::query_as::<_, MilestoneModel>(
+            "SELECT id, wk, title, description, state, due_at, closed_at, created_at, updated_at \
+             FROM milestone WHERE id = $1 AND wk = $2",
+        )
+        .bind(milestone_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::MilestoneNotFound)?;
+
+        let title = params.title.unwrap_or_else(|| milestone.title.clone());
+        let description = params.description.unwrap_or_else(|| {
+            milestone.description.clone().unwrap_or_default()
+        });
+        let state = params.state.unwrap_or_else(|| milestone.state.clone());
+        let due_at = params
+            .due_at
+            .and_then(|d| {
+                chrono::DateTime::parse_from_rfc3339(&d)
+                    .ok()
+                    .map(|dt| dt.to_utc())
+            })
+            .or(milestone.due_at);
+        let closed_at = if state == "closed" && milestone.state != "closed" {
+            Some(chrono::Utc::now())
+        } else {
+            milestone.closed_at
+        };
+
+        let now = chrono::Utc::now();
+        let updated = sqlx::query_as::<_, MilestoneModel>(
+            "UPDATE milestone SET title = $1, description = $2, state = $3, due_at = $4, closed_at = $5, updated_at = $6 \
+             WHERE id = $7 \
+             RETURNING id, wk, title, description, state, due_at, closed_at, created_at, updated_at",
+        )
+        .bind(title)
+        .bind(description)
+        .bind(state)
+        .bind(due_at)
+        .bind(closed_at)
+        .bind(now)
+        .bind(milestone_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(milestone_response(updated))
+    }
+
+    pub async fn milestone_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        milestone_id: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let exists = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM milestone WHERE id = $1 AND wk = $2)",
+        )
+        .bind(milestone_id)
+        .bind(wk.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if !exists {
+            return Err(AppError::MilestoneNotFound);
+        }
+
+        sqlx::query("DELETE FROM issue_milestone WHERE milestone = $1")
+            .bind(milestone_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query("DELETE FROM milestone WHERE id = $1")
+            .bind(milestone_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn issue_set_milestone(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: SetIssueMilestone,
+    ) -> Result<Option<MilestoneResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let milestone = sqlx::query_as::<_, MilestoneModel>(
+            "SELECT id, wk, title, description, state, due_at, closed_at, created_at, updated_at \
+             FROM milestone WHERE id = $1 AND wk = $2",
+        )
+        .bind(params.milestone_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::MilestoneNotFound)?;
+
+        let now = chrono::Utc::now();
+        sqlx::query("DELETE FROM issue_milestone WHERE issue = $1")
+            .bind(issue.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_milestone (issue, milestone, created_at) VALUES ($1, $2, $3)",
+        )
+        .bind(issue.id)
+        .bind(milestone.id)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+             VALUES ($1, $2, $3, 'milestone_changed', NULL, $4, $5)",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&milestone.title)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(Some(milestone_response(milestone)))
+    }
+
+    pub async fn issue_clear_milestone(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let old_milestone = self.issue_milestone(issue.id).await?;
+        if let Some(old) = &old_milestone {
+            sqlx::query("DELETE FROM issue_milestone WHERE issue = $1")
+                .bind(issue.id)
+                .execute(self.db.writer())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+            sqlx::query(
+                "INSERT INTO issue_event (id, issue, actor, event, from_value, to_value, created_at) \
+                 VALUES ($1, $2, $3, 'milestone_removed', $4, NULL, $5)",
+            )
+            .bind(uuid::Uuid::now_v7())
+            .bind(issue.id)
+            .bind(user_uid)
+            .bind(&old.title)
+            .bind(chrono::Utc::now())
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        Ok(())
+    }
+
+    pub(crate) async fn issue_milestone(
+        &self,
+        issue_id: uuid::Uuid,
+    ) -> Result<Option<MilestoneResponse>, AppError> {
+        let milestone = sqlx::query_as::<_, MilestoneModel>(
+            "SELECT m.id, m.wk, m.title, m.description, m.state, m.due_at, m.closed_at, m.created_at, m.updated_at \
+             FROM issue_milestone im \
+             INNER JOIN milestone m ON m.id = im.milestone \
+             WHERE im.issue = $1",
+        )
+        .bind(issue_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(milestone.map(milestone_response))
+    }
+}
diff --git a/lib/service/issues/mod.rs b/lib/service/issues/mod.rs
new file mode 100644
index 0000000..b66e8e0
--- /dev/null
+++ b/lib/service/issues/mod.rs
@@ -0,0 +1,9 @@
+pub mod assignee;
+pub mod binding;
+pub mod comment;
+pub mod event;
+pub mod issue;
+pub mod label;
+pub mod milestone;
+pub mod reaction;
+pub mod types;
diff --git a/lib/service/issues/reaction.rs b/lib/service/issues/reaction.rs
new file mode 100644
index 0000000..f440d98
--- /dev/null
+++ b/lib/service/issues/reaction.rs
@@ -0,0 +1,186 @@
+use db::sqlx;
+use model::issues::IssueReactionModel;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{IssueReactionResponse, issue_author};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AddReaction {
+    pub reaction: String,
+}
+
+impl AppService {
+    pub async fn issue_add_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        params: AddReaction,
+    ) -> Result<Vec<IssueReactionResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+
+        sqlx::query(
+            "INSERT INTO issue_reaction (id, issue, comment, \"user\", reaction, created_at) \
+             VALUES ($1, $2, NULL, $3, $4, $5) \
+             ON CONFLICT (issue, comment, \"user\", reaction) DO NOTHING",
+        )
+        .bind(id)
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(&params.reaction)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_reactions_for(issue.id, None).await
+    }
+
+    pub async fn issue_remove_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        reaction: &str,
+    ) -> Result<Vec<IssueReactionResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        sqlx::query(
+            "DELETE FROM issue_reaction WHERE issue = $1 AND comment IS NULL AND \"user\" = $2 AND reaction = $3",
+        )
+        .bind(issue.id)
+        .bind(user_uid)
+        .bind(reaction)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_reactions_for(issue.id, None).await
+    }
+
+    pub async fn issue_comment_add_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        comment_id: uuid::Uuid,
+        params: AddReaction,
+    ) -> Result<Vec<IssueReactionResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        let exists = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM issue_comment WHERE id = $1 AND issue = $2 AND deleted_at IS NULL)",
+        )
+        .bind(comment_id)
+        .bind(issue.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if !exists {
+            return Err(AppError::CommentNotFound);
+        }
+
+        let id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+
+        sqlx::query(
+            "INSERT INTO issue_reaction (id, issue, comment, \"user\", reaction, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6) \
+             ON CONFLICT (issue, comment, \"user\", reaction) DO NOTHING",
+        )
+        .bind(id)
+        .bind(issue.id)
+        .bind(comment_id)
+        .bind(user_uid)
+        .bind(&params.reaction)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_reactions_for(issue.id, Some(comment_id)).await
+    }
+
+    pub async fn issue_comment_remove_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        number: i64,
+        comment_id: uuid::Uuid,
+        reaction: &str,
+    ) -> Result<Vec<IssueReactionResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let issue = self.issue_resolve(wk.id, number).await?;
+
+        sqlx::query(
+            "DELETE FROM issue_reaction WHERE issue = $1 AND comment = $2 AND \"user\" = $3 AND reaction = $4",
+        )
+        .bind(issue.id)
+        .bind(comment_id)
+        .bind(user_uid)
+        .bind(reaction)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.issue_reactions_for(issue.id, Some(comment_id)).await
+    }
+
+    pub(crate) async fn issue_reactions_for(
+        &self,
+        issue_id: uuid::Uuid,
+        comment_id: Option<uuid::Uuid>,
+    ) -> Result<Vec<IssueReactionResponse>, AppError> {
+        let reactions = if let Some(cid) = comment_id {
+            sqlx::query_as::<_, IssueReactionModel>(
+                "SELECT id, issue, comment, \"user\", reaction, created_at \
+                 FROM issue_reaction WHERE issue = $1 AND comment = $2 \
+                 ORDER BY created_at ASC",
+            )
+            .bind(issue_id)
+            .bind(cid)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        } else {
+            sqlx::query_as::<_, IssueReactionModel>(
+                "SELECT id, issue, comment, \"user\", reaction, created_at \
+                 FROM issue_reaction WHERE issue = $1 AND comment IS NULL \
+                 ORDER BY created_at ASC",
+            )
+            .bind(issue_id)
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        };
+
+        let mut results = Vec::new();
+        for reaction in reactions {
+            let user = self.users_find_by_id(reaction.user).await?;
+            results.push(IssueReactionResponse {
+                id: reaction.id,
+                user: issue_author(user),
+                reaction: reaction.reaction,
+                created_at: reaction.created_at,
+            });
+        }
+        Ok(results)
+    }
+}
diff --git a/lib/service/issues/types.rs b/lib/service/issues/types.rs
new file mode 100644
index 0000000..f6547fd
--- /dev/null
+++ b/lib/service/issues/types.rs
@@ -0,0 +1,164 @@
+use model::{
+    issues::{LabelModel, MilestoneModel},
+    pull_request::PullRequestModel,
+    repos::RepoModel,
+    users::UserModel,
+};
+use serde::{Deserialize, Serialize};
+
+use crate::non_empty;
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssueResponse {
+    pub number: i64,
+    pub title: String,
+    pub body: Option<String>,
+    pub state: String,
+    pub priority: String,
+    #[schema(value_type = Option<String>)]
+    pub due_at: Option<chrono::DateTime<chrono::Utc>>,
+    pub author: IssueAuthor,
+    pub closed_by: Option<IssueAuthor>,
+    #[schema(value_type = Option<String>)]
+    pub closed_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+    pub labels: Vec<LabelResponse>,
+    pub assignees: Vec<IssueAuthor>,
+    pub milestone: Option<MilestoneResponse>,
+    pub repos: Vec<IssueRepoResponse>,
+    pub pull_requests: Vec<IssuePullRequestResponse>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssueAuthor {
+    pub username: String,
+    pub display_name: Option<String>,
+    pub avatar_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct LabelResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+    pub color: String,
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct MilestoneResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub title: String,
+    pub description: Option<String>,
+    pub state: String,
+    #[schema(value_type = Option<String>)]
+    pub due_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssueRepoResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub name: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssuePullRequestResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub number: i64,
+    pub title: String,
+    pub state: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssueCommentResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub author: IssueAuthor,
+    pub body: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssueEventResponse {
+    pub actor: Option<IssueAuthor>,
+    pub event: String,
+    pub from_value: Option<String>,
+    pub to_value: Option<String>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct IssueReactionResponse {
+    #[schema(value_type = String)]
+    pub id: uuid::Uuid,
+    pub user: IssueAuthor,
+    pub reaction: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub(crate) fn issue_author(user: UserModel) -> IssueAuthor {
+    IssueAuthor {
+        username: user.username,
+        display_name: non_empty(user.display_name),
+        avatar_url: non_empty(user.avatar_url),
+    }
+}
+
+pub(crate) fn label_response(label: LabelModel) -> LabelResponse {
+    LabelResponse {
+        id: label.id,
+        name: label.name,
+        color: label.color,
+        description: non_empty(label.description.unwrap_or_default()),
+    }
+}
+
+pub(crate) fn milestone_response(
+    milestone: MilestoneModel,
+) -> MilestoneResponse {
+    MilestoneResponse {
+        id: milestone.id,
+        title: milestone.title,
+        description: non_empty(milestone.description.unwrap_or_default()),
+        state: milestone.state,
+        due_at: milestone.due_at,
+    }
+}
+
+pub(crate) fn issue_repo_response(repo: RepoModel) -> IssueRepoResponse {
+    IssueRepoResponse {
+        id: repo.id,
+        name: repo.name,
+    }
+}
+
+pub(crate) fn issue_pr_response(
+    pr: PullRequestModel,
+) -> IssuePullRequestResponse {
+    IssuePullRequestResponse {
+        id: pr.id,
+        number: pr.number,
+        title: pr.title,
+        state: pr.state,
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::IntoParams)]
+pub struct IssueFilter {
+    pub state: Option<String>,
+    pub label: Option<String>,
+    pub milestone: Option<String>,
+    pub assignee: Option<String>,
+    pub priority: Option<String>,
+}
diff --git a/lib/service/lib.rs b/lib/service/lib.rs
new file mode 100644
index 0000000..7a19d43
--- /dev/null
+++ b/lib/service/lib.rs
@@ -0,0 +1,65 @@
+use cache::AppCache;
+use config::AppConfig;
+use db::AppDatabase;
+use deadpool_redis::cluster::Pool as RedisPool;
+use email::AppEmail;
+use error::AppError;
+use serde::Deserialize;
+use session::Session;
+use storage::AppStorage;
+use tonic::transport::Channel;
+use uuid::Uuid;
+
+pub mod agent;
+pub mod ai;
+pub mod auth;
+pub mod error;
+pub mod git;
+pub mod issues;
+pub mod pull_request;
+pub mod user;
+pub mod users;
+pub mod workspace;
+pub(crate) fn session_user(ctx: &Session) -> Result<Uuid, AppError> {
+    ctx.user().ok_or(AppError::Unauthorized)
+}
+
+pub(crate) fn non_empty(value: String) -> Option<String> {
+    if value.is_empty() { None } else { Some(value) }
+}
+
+pub(crate) fn constant_time_eq(a: &str, b: &str) -> bool {
+    if a.len() != b.len() {
+        return false;
+    }
+    a.bytes()
+        .zip(b.bytes())
+        .fold(0u8, |acc, (x, y)| acc | (x ^ y))
+        == 0
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::IntoParams, utoipa::ToSchema)]
+pub struct Pagination {
+    pub offset: Option<u32>,
+    pub limit: Option<u32>,
+}
+
+impl Pagination {
+    pub fn offset(&self) -> u32 {
+        self.offset.unwrap_or(0)
+    }
+    pub fn limit(&self) -> u32 {
+        self.limit.unwrap_or(20).min(100)
+    }
+}
+
+#[derive(Clone)]
+pub struct AppService {
+    pub db: AppDatabase,
+    pub cache: AppCache,
+    pub email: AppEmail,
+    pub storage: AppStorage,
+    pub config: AppConfig,
+    pub git: Channel,
+    pub redis_pool: RedisPool,
+}
diff --git a/lib/service/pull_request/assignee.rs b/lib/service/pull_request/assignee.rs
new file mode 100644
index 0000000..a94a015
--- /dev/null
+++ b/lib/service/pull_request/assignee.rs
@@ -0,0 +1,110 @@
+use db::sqlx;
+use model::users::UserModel;
+use serde::Deserialize;
+use session::Session;
+
+use crate::{
+    AppService, error::AppError, issues::types::IssueAuthor, session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AssignPrUser {
+    pub username: String,
+}
+
+impl AppService {
+    pub async fn pr_assign(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: AssignPrUser,
+    ) -> Result<Vec<IssueAuthor>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let assignee = sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+             last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE username = $1 AND allow_use = true",
+        )
+        .bind(&params.username)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        sqlx::query(
+            "INSERT INTO pull_request_assignee (pull_request, \"user\", assigned_by, created_at) \
+             VALUES ($1, $2, $3, $4) ON CONFLICT (pull_request, \"user\") DO NOTHING",
+        )
+        .bind(pr.id)
+        .bind(assignee.id)
+        .bind(user_uid)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.pr_assignees_list(pr.id).await
+    }
+
+    pub async fn pr_unassign(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        username: &str,
+    ) -> Result<Vec<IssueAuthor>, AppError> {
+        let _user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let assignee = sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+             last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE username = $1",
+        )
+        .bind(username)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        sqlx::query("DELETE FROM pull_request_assignee WHERE pull_request = $1 AND \"user\" = $2")
+            .bind(pr.id)
+            .bind(assignee.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.pr_assignees_list(pr.id).await
+    }
+
+    pub(crate) async fn pr_assignees_list(
+        &self,
+        pr_id: uuid::Uuid,
+    ) -> Result<Vec<IssueAuthor>, AppError> {
+        let assignees = sqlx::query_as::<_, UserModel>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+             u.last_sign_in_at, u.created_at, u.updated_at \
+             FROM pull_request_assignee pa INNER JOIN \"user\" u ON u.id = pa.\"user\" \
+             WHERE pa.pull_request = $1 \
+             ORDER BY u.username ASC",
+        )
+        .bind(pr_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(assignees
+            .into_iter()
+            .map(|u| crate::issues::types::issue_author(u))
+            .collect())
+    }
+}
diff --git a/lib/service/pull_request/comment.rs b/lib/service/pull_request/comment.rs
new file mode 100644
index 0000000..67973bb
--- /dev/null
+++ b/lib/service/pull_request/comment.rs
@@ -0,0 +1,187 @@
+use db::sqlx;
+use model::pull_request::PullRequestCommentModel;
+use serde::Deserialize;
+use session::Session;
+
+use crate::{
+    AppService, error::AppError,
+    pull_request::types::PullRequestCommentResponse, session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreatePrComment {
+    pub body: String,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdatePrComment {
+    pub body: String,
+}
+
+impl AppService {
+    pub async fn pr_comment_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: CreatePrComment,
+    ) -> Result<PullRequestCommentResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        if params.body.trim().is_empty() {
+            return Err(AppError::BadRequest(
+                "comment body is required".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let comment = sqlx::query_as::<_, PullRequestCommentModel>(
+            "INSERT INTO pull_request_comment (id, pull_request, author, body, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $5) \
+             RETURNING id, pull_request, author, body, created_at, updated_at, deleted_at",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(pr.id)
+        .bind(user_uid)
+        .bind(&params.body)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let author = self.users_find_by_id(user_uid).await?;
+        Ok(PullRequestCommentResponse {
+            id: comment.id,
+            author: crate::issues::types::issue_author(author),
+            body: comment.body,
+            created_at: comment.created_at,
+            updated_at: comment.updated_at,
+        })
+    }
+
+    pub async fn pr_comment_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<Vec<PullRequestCommentResponse>, AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let comments = sqlx::query_as::<_, PullRequestCommentModel>(
+            "SELECT id, pull_request, author, body, created_at, updated_at, deleted_at \
+             FROM pull_request_comment WHERE pull_request = $1 AND deleted_at IS NULL \
+             ORDER BY created_at ASC",
+        )
+        .bind(pr.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for comment in comments {
+            let author = self.users_find_by_id(comment.author).await?;
+            results.push(PullRequestCommentResponse {
+                id: comment.id,
+                author: crate::issues::types::issue_author(author),
+                body: comment.body,
+                created_at: comment.created_at,
+                updated_at: comment.updated_at,
+            });
+        }
+        Ok(results)
+    }
+
+    pub async fn pr_comment_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        _number: i64,
+        comment_id: uuid::Uuid,
+        params: UpdatePrComment,
+    ) -> Result<PullRequestCommentResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let _repo_id = self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        let comment = sqlx::query_as::<_, PullRequestCommentModel>(
+            "SELECT id, pull_request, author, body, created_at, updated_at, deleted_at \
+             FROM pull_request_comment WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(comment_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::CommentNotFound)?;
+
+        if comment.author != user_uid {
+            return Err(AppError::Forbidden(
+                "only the author can update this comment".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let comment = sqlx::query_as::<_, PullRequestCommentModel>(
+            "UPDATE pull_request_comment SET body = $1, updated_at = $2 WHERE id = $3 \
+             RETURNING id, pull_request, author, body, created_at, updated_at, deleted_at",
+        )
+        .bind(&params.body)
+        .bind(now)
+        .bind(comment_id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let author = self.users_find_by_id(comment.author).await?;
+        Ok(PullRequestCommentResponse {
+            id: comment.id,
+            author: crate::issues::types::issue_author(author),
+            body: comment.body,
+            created_at: comment.created_at,
+            updated_at: comment.updated_at,
+        })
+    }
+
+    pub async fn pr_comment_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        comment_id: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let _repo_id = self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        let comment = sqlx::query_as::<_, PullRequestCommentModel>(
+            "SELECT id, pull_request, author, body, created_at, updated_at, deleted_at \
+             FROM pull_request_comment WHERE id = $1 AND deleted_at IS NULL",
+        )
+        .bind(comment_id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::CommentNotFound)?;
+
+        if comment.author != user_uid {
+            let wk = self.workspace_resolve(wk_name).await?;
+            self.workspace_require_admin(wk.id, user_uid).await?;
+        }
+
+        sqlx::query(
+            "UPDATE pull_request_comment SET deleted_at = $1 WHERE id = $2",
+        )
+        .bind(chrono::Utc::now())
+        .bind(comment_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+}
diff --git a/lib/service/pull_request/label.rs b/lib/service/pull_request/label.rs
new file mode 100644
index 0000000..fb78cae
--- /dev/null
+++ b/lib/service/pull_request/label.rs
@@ -0,0 +1,100 @@
+use db::sqlx;
+use model::issues::LabelModel;
+use serde::Deserialize;
+use session::Session;
+use uuid::Uuid;
+
+use crate::{
+    AppService, error::AppError, issues::types::LabelResponse, session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AddPrLabel {
+    pub label_id: Uuid,
+}
+
+impl AppService {
+    pub async fn pr_add_label(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: AddPrLabel,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+        let pr = self.pr_resolve(repo.id, number).await?;
+
+        let _label = sqlx::query_as::<_, LabelModel>(
+            "SELECT id, wk, name, color, description, created_at, updated_at, deleted_at \
+             FROM label WHERE id = $1 AND wk = $2 AND deleted_at IS NULL",
+        )
+        .bind(params.label_id)
+        .bind(wk.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::LabelNotFound)?;
+
+        sqlx::query(
+            "INSERT INTO pull_request_label (pull_request, label, created_at) VALUES ($1, $2, $3) \
+             ON CONFLICT (pull_request, label) DO NOTHING",
+        )
+        .bind(pr.id)
+        .bind(params.label_id)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.pr_labels(pr.id).await
+    }
+
+    pub async fn pr_remove_label(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        label_id: Uuid,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+        let pr = self.pr_resolve(repo.id, number).await?;
+
+        sqlx::query("DELETE FROM pull_request_label WHERE pull_request = $1 AND label = $2")
+            .bind(pr.id)
+            .bind(label_id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.pr_labels(pr.id).await
+    }
+
+    pub(crate) async fn pr_labels(
+        &self,
+        pr_id: uuid::Uuid,
+    ) -> Result<Vec<LabelResponse>, AppError> {
+        let labels = sqlx::query_as::<_, LabelModel>(
+            "SELECT l.id, l.wk, l.name, l.color, l.description, l.created_at, l.updated_at, l.deleted_at \
+             FROM pull_request_label pl INNER JOIN label l ON l.id = pl.label \
+             WHERE pl.pull_request = $1 AND l.deleted_at IS NULL \
+             ORDER BY l.name ASC",
+        )
+        .bind(pr_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(labels
+            .into_iter()
+            .map(crate::issues::types::label_response)
+            .collect())
+    }
+}
diff --git a/lib/service/pull_request/merge.rs b/lib/service/pull_request/merge.rs
new file mode 100644
index 0000000..14c1d71
--- /dev/null
+++ b/lib/service/pull_request/merge.rs
@@ -0,0 +1,244 @@
+use db::sqlx;
+use git::rpc::{proto as p, proto::merge_service_client::MergeServiceClient};
+use serde::Deserialize;
+use session::Session;
+
+use crate::{
+    AppService, error::AppError, git::rpc_err,
+    pull_request::types::PullRequestResponse, session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct MergePullRequest {
+    pub method: Option<String>,
+    pub commit_title: Option<String>,
+    pub commit_message: Option<String>,
+}
+
+impl AppService {
+    pub async fn pr_merge_analysis(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<p::MergeAnalysisResponse, AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let mut client = MergeServiceClient::new(self.git.clone());
+        let resp = client
+            .merge_analysis(tonic::Request::new(p::MergeAnalysisRequest {
+                repo_id: repo_id.to_string(),
+                oid_a: Some(p::ObjectId {
+                    value: pr.source_sha.clone(),
+                }),
+                oid_b: Some(p::ObjectId {
+                    value: pr.target_sha.clone(),
+                }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn pr_merge_base(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<p::MergeBaseResponse, AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let mut client = MergeServiceClient::new(self.git.clone());
+        let resp = client
+            .merge_base(tonic::Request::new(p::MergeBaseRequest {
+                repo_id: repo_id.to_string(),
+                oid_a: Some(p::ObjectId {
+                    value: pr.source_sha.clone(),
+                }),
+                oid_b: Some(p::ObjectId {
+                    value: pr.target_sha.clone(),
+                }),
+            }))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        Ok(resp)
+    }
+
+    pub async fn pr_merge(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: MergePullRequest,
+    ) -> Result<PullRequestResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo_admin(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        if pr.state != "open" {
+            return Err(AppError::BadRequest(
+                "pull request is not open".to_string(),
+            ));
+        }
+        if pr.draft {
+            return Err(AppError::BadRequest(
+                "draft pull request cannot be merged".to_string(),
+            ));
+        }
+
+        let method = params.method.unwrap_or_else(|| "merge".to_string());
+        let now = chrono::Utc::now();
+
+        let merge_result_sha = match method.as_str() {
+            "merge" => {
+                let mut client = MergeServiceClient::new(self.git.clone());
+                let resp = client
+                    .merge_commit(tonic::Request::new(p::MergeCommitRequest {
+                        repo_id: repo_id.to_string(),
+                        params: Some(p::MergeCommitParams {
+                            their_commit: Some(p::ObjectId {
+                                value: pr.source_sha.clone(),
+                            }),
+                            author: Some(p::CommitSignature {
+                                name: format!("merge: {}", pr.title),
+                                email: "noreply@gitdata.ai".to_string(),
+                                time_secs: now.timestamp(),
+                                offset_minutes: 0,
+                            }),
+                            committer: Some(p::CommitSignature {
+                                name: "gitdata".to_string(),
+                                email: "noreply@gitdata.ai".to_string(),
+                                time_secs: now.timestamp(),
+                                offset_minutes: 0,
+                            }),
+                            message: params.commit_message.unwrap_or_else(
+                                || {
+                                    format!(
+                                        "Merge pull request #{}: {}",
+                                        pr.number, pr.title
+                                    )
+                                },
+                            ),
+                            update_ref: Some(format!(
+                                "refs/heads/{}",
+                                pr.target_branch
+                            )),
+                            options: None,
+                        }),
+                    }))
+                    .await
+                    .map_err(rpc_err)?
+                    .into_inner();
+                resp.oid.map(|oid| oid.value).unwrap_or_default()
+            }
+            "squash" => {
+                let mut client = MergeServiceClient::new(self.git.clone());
+                let resp = client
+                    .squash_commit(tonic::Request::new(
+                        p::SquashCommitRequest {
+                            repo_id: repo_id.to_string(),
+                            params: Some(p::SquashCommitParams {
+                                their_commit: Some(p::ObjectId {
+                                    value: pr.source_sha.clone(),
+                                }),
+                                options: None,
+                            }),
+                        },
+                    ))
+                    .await
+                    .map_err(rpc_err)?
+                    .into_inner();
+                resp.oid.map(|oid| oid.value).unwrap_or_default()
+            }
+            _ => {
+                return Err(AppError::BadRequest(
+                    "merge method must be 'merge' or 'squash'".to_string(),
+                ));
+            }
+        };
+
+        sqlx::query(
+            "UPDATE pull_request SET state = 'merged', merged_by = $1, merged_at = $2, \
+             target_sha = $3, updated_at = $2 WHERE id = $4",
+        )
+        .bind(user_uid)
+        .bind(now)
+        .bind(&merge_result_sha)
+        .bind(pr.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let pr = self.pr_resolve(repo_id, number).await?;
+        self.pr_build_response(pr).await
+    }
+
+    pub async fn pr_merge_abort(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<(), AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo_admin(ctx, wk_name, repo_name).await?;
+
+        let mut client = MergeServiceClient::new(self.git.clone());
+        client
+            .merge_abort(tonic::Request::new(p::MergeAbortRequest {
+                repo_id: repo_id.to_string(),
+            }))
+            .await
+            .map_err(rpc_err)?;
+
+        Ok(())
+    }
+
+    pub async fn pr_update_branch(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<PullRequestResponse, AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        if pr.state != "open" {
+            return Err(AppError::BadRequest(
+                "pull request is not open".to_string(),
+            ));
+        }
+
+        let source_sha = self
+            .branch_head_sha(pr.source_repo, &pr.source_branch)
+            .await?;
+        let target_sha =
+            self.branch_head_sha(repo_id, &pr.target_branch).await?;
+        let now = chrono::Utc::now();
+
+        sqlx::query(
+            "UPDATE pull_request SET source_sha = $1, target_sha = $2, updated_at = $3 WHERE id = $4",
+        )
+        .bind(&source_sha)
+        .bind(&target_sha)
+        .bind(now)
+        .bind(pr.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let pr = self.pr_resolve(repo_id, number).await?;
+        self.pr_build_response(pr).await
+    }
+}
diff --git a/lib/service/pull_request/mod.rs b/lib/service/pull_request/mod.rs
new file mode 100644
index 0000000..ef5472b
--- /dev/null
+++ b/lib/service/pull_request/mod.rs
@@ -0,0 +1,78 @@
+pub mod assignee;
+pub mod comment;
+pub mod label;
+pub mod merge;
+pub mod pull_request;
+pub mod reaction;
+pub mod review;
+pub mod types;
+
+use db::sqlx;
+use git::rpc::proto::branch_service_client::BranchServiceClient;
+use model::{pull_request::PullRequestModel, repos::RepoModel};
+use session::Session;
+
+use crate::{AppService, error::AppError, git::rpc_err};
+
+impl AppService {
+    pub(crate) async fn pr_resolve(
+        &self,
+        repo_id: uuid::Uuid,
+        number: i64,
+    ) -> Result<PullRequestModel, AppError> {
+        sqlx::query_as::<_, PullRequestModel>(
+            "SELECT id, repo, number, title, body, state, draft, author, \
+             source_repo, source_branch, source_sha, target_branch, target_sha, \
+             merged_by, merged_at, closed_by, closed_at, created_at, updated_at, deleted_at \
+             FROM pull_request WHERE repo = $1 AND number = $2 AND deleted_at IS NULL",
+        )
+        .bind(repo_id)
+        .bind(number)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::PullRequestNotFound)
+    }
+
+    pub(crate) async fn pr_resolve_repo(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<(uuid::Uuid, RepoModel), AppError> {
+        let repo = self.git_require_member(ctx, wk_name, repo_name).await?;
+        Ok((repo.id, repo))
+    }
+
+    pub(crate) async fn pr_resolve_repo_admin(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+    ) -> Result<(uuid::Uuid, RepoModel), AppError> {
+        let repo = self.git_require_admin(ctx, wk_name, repo_name).await?;
+        Ok((repo.id, repo))
+    }
+
+    pub(crate) async fn branch_head_sha(
+        &self,
+        repo_id: uuid::Uuid,
+        branch: &str,
+    ) -> Result<String, AppError> {
+        let mut client = BranchServiceClient::new(self.git.clone());
+        let resp = client
+            .branch_info(tonic::Request::new(
+                git::rpc::proto::BranchInfoRequest {
+                    repo_id: repo_id.to_string(),
+                    branch: branch.to_string(),
+                },
+            ))
+            .await
+            .map_err(rpc_err)?
+            .into_inner();
+        let sha = resp.branch.and_then(|b| b.oid).map(|oid| oid.value).ok_or(
+            AppError::NotFound(format!("branch '{}' not found", branch)),
+        )?;
+        Ok(sha)
+    }
+}
diff --git a/lib/service/pull_request/pull_request.rs b/lib/service/pull_request/pull_request.rs
new file mode 100644
index 0000000..7c2df1a
--- /dev/null
+++ b/lib/service/pull_request/pull_request.rs
@@ -0,0 +1,409 @@
+use db::{sqlx, sqlx::AssertSqlSafe};
+use model::pull_request::PullRequestModel;
+use serde::Deserialize;
+use session::Session;
+
+use crate::{
+    AppService, Pagination,
+    error::AppError,
+    issues::types::issue_author,
+    pull_request::types::{PullRequestFilter, PullRequestResponse},
+    session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreatePullRequest {
+    pub title: String,
+    pub body: Option<String>,
+    pub source_branch: String,
+    pub target_branch: Option<String>,
+    pub source_repo: Option<String>,
+    pub draft: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdatePullRequest {
+    pub title: Option<String>,
+    pub body: Option<Option<String>>,
+    pub draft: Option<bool>,
+    pub state: Option<String>,
+}
+
+impl AppService {
+    pub async fn pr_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        params: CreatePullRequest,
+    ) -> Result<PullRequestResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, repo) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        let title = params.title.trim();
+        if title.is_empty() {
+            return Err(AppError::BadRequest(
+                "pull request title is required".to_string(),
+            ));
+        }
+
+        let target_branch = params
+            .target_branch
+            .unwrap_or_else(|| repo.default_branch.clone());
+        let source_repo_name =
+            params.source_repo.unwrap_or_else(|| repo_name.to_string());
+
+        let source_repo_id = if source_repo_name == repo_name {
+            repo_id
+        } else {
+            let wk = self.workspace_resolve(wk_name).await?;
+            let source_repo =
+                self.repo_resolve(wk.id, &source_repo_name).await?;
+            source_repo.id
+        };
+
+        let source_sha = self
+            .branch_head_sha(source_repo_id, &params.source_branch)
+            .await?;
+        let target_sha = self.branch_head_sha(repo_id, &target_branch).await?;
+
+        if source_sha == target_sha {
+            return Err(AppError::Conflict(
+                "source and target branches are the same".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let id = uuid::Uuid::now_v7();
+
+        let pr = sqlx::query_as::<_, PullRequestModel>(
+            "INSERT INTO pull_request (id, repo, number, title, body, state, draft, author, \
+             source_repo, source_branch, source_sha, target_branch, target_sha, \
+             merged_by, merged_at, closed_by, closed_at, created_at, updated_at) \
+             VALUES ($1, $2, (SELECT COALESCE(MAX(number), 0) + 1 FROM pull_request WHERE repo = $2 AND deleted_at IS NULL), \
+             $3, $4, 'open', $5, $6, $7, $8, $9, $10, $11, NULL, NULL, NULL, NULL, $12, $12) \
+             RETURNING id, repo, number, title, body, state, draft, author, \
+             source_repo, source_branch, source_sha, target_branch, target_sha, \
+             merged_by, merged_at, closed_by, closed_at, created_at, updated_at, deleted_at",
+        )
+        .bind(id)
+        .bind(repo_id)
+        .bind(title)
+        .bind(&params.body)
+        .bind(params.draft.unwrap_or(false))
+        .bind(user_uid)
+        .bind(source_repo_id)
+        .bind(&params.source_branch)
+        .bind(&source_sha)
+        .bind(&target_branch)
+        .bind(&target_sha)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.pr_build_response(pr).await
+    }
+
+    pub async fn pr_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        filter: PullRequestFilter,
+        pagination: Pagination,
+    ) -> Result<Vec<PullRequestResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(wk_name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let repo = self.repo_resolve(wk.id, repo_name).await?;
+
+        let mut conditions = vec![
+            "pr.repo = $1".to_string(),
+            "pr.deleted_at IS NULL".to_string(),
+        ];
+        let mut param_idx = 2;
+
+        if filter.state.is_some() {
+            conditions.push(format!("pr.state = ${param_idx}"));
+            param_idx += 1;
+        }
+        if filter.author.is_some() {
+            conditions.push(format!(
+                "EXISTS(SELECT 1 FROM \"user\" u WHERE u.id = pr.author AND u.username = ${param_idx})"
+            ));
+            param_idx += 1;
+        }
+        if filter.assignee.is_some() {
+            conditions.push(format!(
+                "EXISTS(SELECT 1 FROM pull_request_assignee pa INNER JOIN \"user\" u ON u.id = pa.\"user\" \
+                 WHERE pa.pull_request = pr.id AND u.username = ${param_idx})"
+            ));
+            param_idx += 1;
+        }
+        if filter.label.is_some() {
+            conditions.push(format!(
+                "EXISTS(SELECT 1 FROM pull_request_label pl INNER JOIN label l ON l.id = pl.label \
+                 WHERE pl.pull_request = pr.id AND l.name = ${param_idx})"
+            ));
+            param_idx += 1;
+        }
+
+        let where_clause = conditions.join(" AND ");
+        let limit_idx = param_idx;
+        let offset_idx = param_idx + 1;
+
+        let query = format!(
+            "SELECT pr.id, pr.repo, pr.number, pr.title, pr.body, pr.state, pr.draft, pr.author, \
+             pr.source_repo, pr.source_branch, pr.source_sha, pr.target_branch, pr.target_sha, \
+             pr.merged_by, pr.merged_at, pr.closed_by, pr.closed_at, pr.created_at, pr.updated_at, pr.deleted_at \
+             FROM pull_request pr WHERE {where_clause} \
+             ORDER BY pr.created_at DESC LIMIT ${limit_idx} OFFSET ${offset_idx}"
+        );
+
+        let mut q = sqlx::query_as::<_, PullRequestModel>(AssertSqlSafe(query))
+            .bind(repo.id);
+        if let Some(state) = &filter.state {
+            q = q.bind(state);
+        }
+        if let Some(author) = &filter.author {
+            q = q.bind(author);
+        }
+        if let Some(assignee) = &filter.assignee {
+            q = q.bind(assignee);
+        }
+        if let Some(label) = &filter.label {
+            q = q.bind(label);
+        }
+        q = q
+            .bind(pagination.limit() as i64)
+            .bind(pagination.offset() as i64);
+
+        let prs = q
+            .fetch_all(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for pr in prs {
+            results.push(self.pr_build_response(pr).await?);
+        }
+        Ok(results)
+    }
+
+    pub async fn pr_get(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<PullRequestResponse, AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+        self.pr_build_response(pr).await
+    }
+
+    pub async fn pr_update(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: UpdatePullRequest,
+    ) -> Result<PullRequestResponse, AppError> {
+        if let Some(ref state) = params.state {
+            return match state.as_str() {
+                "closed" => self.pr_close(ctx, wk_name, repo_name, number).await,
+                "open" => self.pr_reopen(ctx, wk_name, repo_name, number).await,
+                other => Err(AppError::BadRequest(format!(
+                    "invalid state '{}': must be 'open' or 'closed'", other
+                ))),
+            };
+        }
+
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let mut pr = self.pr_resolve(repo_id, number).await?;
+
+        if pr.author != user_uid {
+            return Err(AppError::Forbidden(
+                "only the author can update this pull request".to_string(),
+            ));
+        }
+        if pr.state != "open" {
+            return Err(AppError::BadRequest(
+                "cannot update a closed or merged pull request".to_string(),
+            ));
+        }
+
+        let next_title = params
+            .title
+            .map(|t| t.trim().to_string())
+            .unwrap_or(pr.title.clone());
+        if next_title.is_empty() {
+            return Err(AppError::BadRequest(
+                "pull request title is required".to_string(),
+            ));
+        }
+        let next_body = params.body.map(Some).unwrap_or(Some(pr.body.clone()));
+        let next_draft = params.draft.unwrap_or(pr.draft);
+        let now = chrono::Utc::now();
+
+        pr = sqlx::query_as::<_, PullRequestModel>(
+            "UPDATE pull_request SET title = $1, body = $2, draft = $3, updated_at = $4 WHERE id = $5 \
+             RETURNING id, repo, number, title, body, state, draft, author, \
+             source_repo, source_branch, source_sha, target_branch, target_sha, \
+             merged_by, merged_at, closed_by, closed_at, created_at, updated_at, deleted_at",
+        )
+        .bind(&next_title)
+        .bind(&next_body)
+        .bind(next_draft)
+        .bind(now)
+        .bind(pr.id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.pr_build_response(pr).await
+    }
+
+    pub async fn pr_close(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<PullRequestResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        if pr.state != "open" {
+            return Err(AppError::BadRequest(
+                "pull request is already closed or merged".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "UPDATE pull_request SET state = 'closed', closed_by = $1, closed_at = $2, updated_at = $2 WHERE id = $3",
+        )
+        .bind(user_uid)
+        .bind(now)
+        .bind(pr.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let pr = self.pr_resolve(repo_id, number).await?;
+        self.pr_build_response(pr).await
+    }
+
+    pub async fn pr_reopen(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<PullRequestResponse, AppError> {
+        let _user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        if pr.state != "closed" {
+            return Err(AppError::BadRequest(
+                "pull request is not closed".to_string(),
+            ));
+        }
+        if pr.merged_by.is_some() {
+            return Err(AppError::BadRequest(
+                "merged pull request cannot be reopened".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "UPDATE pull_request SET state = 'open', closed_by = NULL, closed_at = NULL, updated_at = $1 WHERE id = $2",
+        )
+        .bind(now)
+        .bind(pr.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let pr = self.pr_resolve(repo_id, number).await?;
+        self.pr_build_response(pr).await
+    }
+
+    pub async fn pr_delete(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<(), AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo_admin(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        sqlx::query("UPDATE pull_request SET deleted_at = $1 WHERE id = $2")
+            .bind(chrono::Utc::now())
+            .bind(pr.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn pr_build_response(
+        &self,
+        pr: PullRequestModel,
+    ) -> Result<PullRequestResponse, AppError> {
+        let author = self.users_find_by_id(pr.author).await?;
+
+        let merged_by = if let Some(uid) = pr.merged_by {
+            Some(issue_author(self.users_find_by_id(uid).await?))
+        } else {
+            None
+        };
+
+        let closed_by = if let Some(uid) = pr.closed_by {
+            Some(issue_author(self.users_find_by_id(uid).await?))
+        } else {
+            None
+        };
+
+        let labels = self.pr_labels(pr.id).await?;
+        let assignees = self.pr_assignees_list(pr.id).await?;
+        let reviews = self.pr_reviews_list(pr.id).await?;
+
+        Ok(PullRequestResponse {
+            number: pr.number,
+            title: pr.title,
+            body: pr.body,
+            state: pr.state,
+            draft: pr.draft,
+            author: issue_author(author),
+            source_repo: pr.source_repo,
+            source_branch: pr.source_branch,
+            source_sha: pr.source_sha,
+            target_branch: pr.target_branch,
+            target_sha: pr.target_sha,
+            merged_by,
+            merged_at: pr.merged_at,
+            closed_by,
+            closed_at: pr.closed_at,
+            created_at: pr.created_at,
+            updated_at: pr.updated_at,
+            labels,
+            assignees,
+            reviews,
+        })
+    }
+}
diff --git a/lib/service/pull_request/reaction.rs b/lib/service/pull_request/reaction.rs
new file mode 100644
index 0000000..7ab775d
--- /dev/null
+++ b/lib/service/pull_request/reaction.rs
@@ -0,0 +1,140 @@
+use db::sqlx;
+use model::pull_request::PullRequestReactionModel;
+use serde::Deserialize;
+use session::Session;
+use uuid::Uuid;
+
+use crate::{
+    AppService, error::AppError,
+    pull_request::types::PullRequestReactionResponse, session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AddPrReaction {
+    pub reaction: String,
+}
+
+impl AppService {
+    pub async fn pr_add_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: AddPrReaction,
+    ) -> Result<PullRequestReactionResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let now = chrono::Utc::now();
+        let reaction = sqlx::query_as::<_, PullRequestReactionModel>(
+            "INSERT INTO pull_request_reaction (id, pull_request, comment, \"user\", reaction, created_at) \
+             VALUES ($1, $2, NULL, $3, $4, $5) \
+             RETURNING id, pull_request, comment, \"user\", reaction, created_at",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(pr.id)
+        .bind(user_uid)
+        .bind(&params.reaction)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let user = self.users_find_by_id(reaction.user).await?;
+        Ok(PullRequestReactionResponse {
+            id: reaction.id,
+            user: crate::issues::types::issue_author(user),
+            reaction: reaction.reaction,
+            created_at: reaction.created_at,
+        })
+    }
+
+    pub async fn pr_remove_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        _number: i64,
+        reaction_id: Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let (_repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        sqlx::query(
+            "DELETE FROM pull_request_reaction WHERE id = $1 AND \"user\" = $2",
+        )
+        .bind(reaction_id)
+        .bind(user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn pr_comment_add_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        _number: i64,
+        comment_id: Uuid,
+        params: AddPrReaction,
+    ) -> Result<PullRequestReactionResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        let now = chrono::Utc::now();
+        let reaction = sqlx::query_as::<_, PullRequestReactionModel>(
+            "INSERT INTO pull_request_reaction (id, pull_request, comment, \"user\", reaction, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6) \
+             RETURNING id, pull_request, comment, \"user\", reaction, created_at",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(repo_id)
+        .bind(comment_id)
+        .bind(user_uid)
+        .bind(&params.reaction)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let user = self.users_find_by_id(reaction.user).await?;
+        Ok(PullRequestReactionResponse {
+            id: reaction.id,
+            user: crate::issues::types::issue_author(user),
+            reaction: reaction.reaction,
+            created_at: reaction.created_at,
+        })
+    }
+
+    pub async fn pr_comment_remove_reaction(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        _number: i64,
+        reaction_id: Uuid,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let (_repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        sqlx::query(
+            "DELETE FROM pull_request_reaction WHERE id = $1 AND \"user\" = $2",
+        )
+        .bind(reaction_id)
+        .bind(user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+}
diff --git a/lib/service/pull_request/review.rs b/lib/service/pull_request/review.rs
new file mode 100644
index 0000000..5a94d2b
--- /dev/null
+++ b/lib/service/pull_request/review.rs
@@ -0,0 +1,240 @@
+use db::sqlx;
+use model::pull_request::{
+    PullRequestReviewCommentModel, PullRequestReviewModel,
+};
+use serde::Deserialize;
+use session::Session;
+use uuid::Uuid;
+
+use crate::{
+    AppService,
+    error::AppError,
+    pull_request::types::{
+        PullRequestReviewCommentResponse, PullRequestReviewResponse,
+    },
+    session_user,
+};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreatePrReview {
+    pub state: String,
+    pub body: Option<String>,
+    pub commit_sha: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreatePrReviewComment {
+    pub body: String,
+    pub path: String,
+    pub line: Option<i32>,
+    pub side: Option<String>,
+    pub commit_sha: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct DismissPrReview {
+    pub dismiss_reason: Option<String>,
+}
+
+impl AppService {
+    pub async fn pr_review_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        params: CreatePrReview,
+    ) -> Result<PullRequestReviewResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let valid_states =
+            ["pending", "commented", "approved", "changes_requested"];
+        if !valid_states.contains(&params.state.as_str()) {
+            return Err(AppError::BadRequest(format!(
+                "invalid review state: {}",
+                params.state
+            )));
+        }
+
+        let now = chrono::Utc::now();
+        let review = sqlx::query_as::<_, PullRequestReviewModel>(
+            "INSERT INTO pull_request_review (id, pull_request, reviewer, state, body, commit_sha, \
+             submitted_at, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $7, $7) \
+             RETURNING id, pull_request, reviewer, state, body, commit_sha, submitted_at, \
+             created_at, updated_at, dismissed_by, dismissed_at, dismiss_reason",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(pr.id)
+        .bind(user_uid)
+        .bind(&params.state)
+        .bind(&params.body)
+        .bind(&params.commit_sha)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let reviewer = self.users_find_by_id(review.reviewer).await?;
+        Ok(PullRequestReviewResponse {
+            id: review.id,
+            reviewer: crate::issues::types::issue_author(reviewer),
+            state: review.state,
+            body: review.body,
+            commit_sha: review.commit_sha,
+            submitted_at: review.submitted_at,
+            created_at: review.created_at,
+        })
+    }
+
+    pub async fn pr_review_list(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+    ) -> Result<Vec<PullRequestReviewResponse>, AppError> {
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let reviews = sqlx::query_as::<_, PullRequestReviewModel>(
+            "SELECT id, pull_request, reviewer, state, body, commit_sha, submitted_at, \
+             created_at, updated_at, dismissed_by, dismissed_at, dismiss_reason \
+             FROM pull_request_review WHERE pull_request = $1 \
+             ORDER BY created_at DESC",
+        )
+        .bind(pr.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for review in reviews {
+            let reviewer = self.users_find_by_id(review.reviewer).await?;
+            results.push(PullRequestReviewResponse {
+                id: review.id,
+                reviewer: crate::issues::types::issue_author(reviewer),
+                state: review.state,
+                body: review.body,
+                commit_sha: review.commit_sha,
+                submitted_at: review.submitted_at,
+                created_at: review.created_at,
+            });
+        }
+        Ok(results)
+    }
+
+    pub async fn pr_review_dismiss(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        _number: i64,
+        review_id: Uuid,
+        params: DismissPrReview,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let _repo_id = self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+
+        sqlx::query(
+            "UPDATE pull_request_review SET state = 'dismissed', dismissed_by = $1, dismissed_at = $2, \
+             dismiss_reason = $3, updated_at = $2 WHERE id = $4",
+        )
+        .bind(user_uid)
+        .bind(chrono::Utc::now())
+        .bind(&params.dismiss_reason)
+        .bind(review_id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(())
+    }
+
+    pub async fn pr_review_comment_create(
+        &self,
+        ctx: &Session,
+        wk_name: &str,
+        repo_name: &str,
+        number: i64,
+        review_id: Option<Uuid>,
+        params: CreatePrReviewComment,
+    ) -> Result<PullRequestReviewCommentResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let (repo_id, _) =
+            self.pr_resolve_repo(ctx, wk_name, repo_name).await?;
+        let pr = self.pr_resolve(repo_id, number).await?;
+
+        let now = chrono::Utc::now();
+        let comment = sqlx::query_as::<_, PullRequestReviewCommentModel>(
+            "INSERT INTO pull_request_review_comment (id, pull_request, review, author, body, path, \
+             commit_sha, original_commit_sha, line, original_line, side, resolved, \
+             created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, NULL, $8, $8, $9, false, $10, $10) \
+             RETURNING id, pull_request, review, author, body, path, commit_sha, \
+             original_commit_sha, line, original_line, side, resolved, resolved_by, resolved_at, \
+             created_at, updated_at, deleted_at",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(pr.id)
+        .bind(review_id)
+        .bind(user_uid)
+        .bind(&params.body)
+        .bind(&params.path)
+        .bind(params.commit_sha.unwrap_or(pr.source_sha.clone()))
+        .bind(params.line)
+        .bind(&params.side)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let author = self.users_find_by_id(comment.author).await?;
+        Ok(PullRequestReviewCommentResponse {
+            id: comment.id,
+            author: crate::issues::types::issue_author(author),
+            path: comment.path,
+            line: comment.line,
+            body: comment.body,
+            commit_sha: comment.commit_sha,
+            resolved: comment.resolved,
+            created_at: comment.created_at,
+            updated_at: comment.updated_at,
+        })
+    }
+
+    pub(crate) async fn pr_reviews_list(
+        &self,
+        pr_id: uuid::Uuid,
+    ) -> Result<Vec<PullRequestReviewResponse>, AppError> {
+        let reviews = sqlx::query_as::<_, PullRequestReviewModel>(
+            "SELECT id, pull_request, reviewer, state, body, commit_sha, submitted_at, \
+             created_at, updated_at, dismissed_by, dismissed_at, dismiss_reason \
+             FROM pull_request_review WHERE pull_request = $1 \
+             ORDER BY created_at DESC",
+        )
+        .bind(pr_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut results = Vec::new();
+        for review in reviews {
+            let reviewer = self.users_find_by_id(review.reviewer).await?;
+            results.push(PullRequestReviewResponse {
+                id: review.id,
+                reviewer: crate::issues::types::issue_author(reviewer),
+                state: review.state,
+                body: review.body,
+                commit_sha: review.commit_sha,
+                submitted_at: review.submitted_at,
+                created_at: review.created_at,
+            });
+        }
+        Ok(results)
+    }
+}
diff --git a/lib/service/pull_request/types.rs b/lib/service/pull_request/types.rs
new file mode 100644
index 0000000..8f2371c
--- /dev/null
+++ b/lib/service/pull_request/types.rs
@@ -0,0 +1,93 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::issues::types::{IssueAuthor, LabelResponse};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct PullRequestResponse {
+    pub number: i64,
+    pub title: String,
+    pub body: Option<String>,
+    pub state: String,
+    pub draft: bool,
+    pub author: IssueAuthor,
+    #[schema(value_type = String)]
+    pub source_repo: Uuid,
+    pub source_branch: String,
+    pub source_sha: String,
+    pub target_branch: String,
+    pub target_sha: String,
+    pub merged_by: Option<IssueAuthor>,
+    #[schema(value_type = Option<String>)]
+    pub merged_at: Option<chrono::DateTime<chrono::Utc>>,
+    pub closed_by: Option<IssueAuthor>,
+    #[schema(value_type = Option<String>)]
+    pub closed_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+    pub labels: Vec<LabelResponse>,
+    pub assignees: Vec<IssueAuthor>,
+    pub reviews: Vec<PullRequestReviewResponse>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct PullRequestCommentResponse {
+    #[schema(value_type = String)]
+    pub id: Uuid,
+    pub author: IssueAuthor,
+    pub body: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct PullRequestReviewResponse {
+    #[schema(value_type = String)]
+    pub id: Uuid,
+    pub reviewer: IssueAuthor,
+    pub state: String,
+    pub body: Option<String>,
+    pub commit_sha: Option<String>,
+    #[schema(value_type = Option<String>)]
+    pub submitted_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct PullRequestReviewCommentResponse {
+    #[schema(value_type = String)]
+    pub id: Uuid,
+    pub author: IssueAuthor,
+    pub path: String,
+    pub line: Option<i32>,
+    pub body: String,
+    pub commit_sha: String,
+    pub resolved: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct PullRequestReactionResponse {
+    #[schema(value_type = String)]
+    pub id: Uuid,
+    pub user: IssueAuthor,
+    pub reaction: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::IntoParams)]
+pub struct PullRequestFilter {
+    pub state: Option<String>,
+    pub author: Option<String>,
+    pub assignee: Option<String>,
+    pub label: Option<String>,
+}
diff --git a/lib/service/user/access_token.rs b/lib/service/user/access_token.rs
new file mode 100644
index 0000000..ff46e83
--- /dev/null
+++ b/lib/service/user/access_token.rs
@@ -0,0 +1,230 @@
+use argon2::{Argon2, password_hash::PasswordHasher};
+use db::sqlx;
+use model::users::UserTokenModel;
+use rand::{RngExt, distr::Alphanumeric};
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserAccessToken {
+    pub id: i64,
+    pub name: String,
+    pub scopes: Vec<String>,
+    #[schema(value_type = Option<String>)]
+    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
+    pub is_revoked: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct CreatedUserAccessToken {
+    pub token: String,
+    pub access_token: UserAccessToken,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateUserAccessToken {
+    pub name: String,
+    pub scopes: Vec<String>,
+    #[schema(value_type = Option<String>)]
+    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserAccessToken {
+    pub name: Option<String>,
+    pub scopes: Option<Vec<String>>,
+    #[schema(value_type = Option<String>)]
+    pub expires_at: Option<Option<chrono::DateTime<chrono::Utc>>>,
+}
+
+impl AppService {
+    pub async fn user_access_tokens(
+        &self,
+        ctx: &Session,
+    ) -> Result<Vec<UserAccessToken>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let rows = sqlx::query_as::<_, UserTokenModel>(
+            "SELECT id, \"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at \
+             FROM user_token WHERE \"user\" = $1 ORDER BY created_at DESC",
+        )
+        .bind(user_uid)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    pub async fn user_create_access_token(
+        &self,
+        ctx: &Session,
+        params: CreateUserAccessToken,
+    ) -> Result<CreatedUserAccessToken, AppError> {
+        let user_uid = session_user(ctx)?;
+        let name = params.name.trim();
+        if name.is_empty() {
+            return Err(AppError::BadRequest(
+                "token name is required".to_string(),
+            ));
+        }
+
+        let token = generate_access_token();
+        let token_hash = Argon2::default()
+            .hash_password(token.as_bytes())
+            .map_err(|e| AppError::PasswordHashError(e.to_string()))?
+            .to_string();
+        let scopes = normalize_scopes(params.scopes);
+        let scopes_str = scopes.join(".");
+        let now = chrono::Utc::now();
+
+        let row = sqlx::query_as::<_, UserTokenModel>(
+            "INSERT INTO user_token (\"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, false, $6, $6) \
+             RETURNING id, \"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at",
+        )
+        .bind(user_uid)
+        .bind(name)
+        .bind(&token_hash)
+        .bind(&scopes_str)
+        .bind(params.expires_at)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(CreatedUserAccessToken {
+            token,
+            access_token: row.into(),
+        })
+    }
+
+    pub async fn user_revoke_access_token(
+        &self,
+        ctx: &Session,
+        token_id: i64,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let affected = sqlx::query(
+            "UPDATE user_token SET is_revoked = true, updated_at = $1 \
+             WHERE id = $2 AND \"user\" = $3 AND is_revoked = false",
+        )
+        .bind(chrono::Utc::now())
+        .bind(token_id)
+        .bind(user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .rows_affected();
+
+        if affected == 0 {
+            return Err(AppError::NotFound(
+                "access token not found".to_string(),
+            ));
+        }
+        Ok(())
+    }
+
+    pub async fn user_update_access_token(
+        &self,
+        ctx: &Session,
+        token_id: i64,
+        params: UpdateUserAccessToken,
+    ) -> Result<UserAccessToken, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut token =
+            self.user_access_token_by_id(user_uid, token_id).await?;
+
+        if let Some(name) = params.name {
+            let name = name.trim();
+            if name.is_empty() {
+                return Err(AppError::BadRequest(
+                    "token name is required".to_string(),
+                ));
+            }
+            token.name = name.to_string();
+        }
+        if let Some(scopes) = params.scopes {
+            token.scopes = normalize_scopes(scopes);
+        }
+        if let Some(expires_at) = params.expires_at {
+            token.expires_at = expires_at;
+        }
+
+        let row = sqlx::query_as::<_, UserTokenModel>(
+            "UPDATE user_token SET name = $1, scopes = $2, expires_at = $3, updated_at = $4 \
+             WHERE id = $5 AND \"user\" = $6 AND is_revoked = false \
+             RETURNING id, \"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at",
+        )
+        .bind(&token.name)
+        .bind(token.scopes.join("."))
+        .bind(token.expires_at)
+        .bind(chrono::Utc::now())
+        .bind(token_id)
+        .bind(user_uid)
+        .fetch_optional(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("access token not found".to_string()))?;
+
+        Ok(row.into())
+    }
+
+    async fn user_access_token_by_id(
+        &self,
+        user_uid: uuid::Uuid,
+        token_id: i64,
+    ) -> Result<UserAccessToken, AppError> {
+        sqlx::query_as::<_, UserTokenModel>(
+            "SELECT id, \"user\", name, token_hash, scopes, expires_at, is_revoked, created_at, updated_at \
+             FROM user_token WHERE id = $1 AND \"user\" = $2 AND is_revoked = false",
+        )
+        .bind(token_id)
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .map(Into::into)
+        .ok_or_else(|| AppError::NotFound("access token not found".to_string()))
+    }
+}
+
+fn normalize_scopes(scopes: Vec<String>) -> Vec<String> {
+    scopes
+        .into_iter()
+        .map(|scope| scope.trim().to_string())
+        .filter(|scope| !scope.is_empty() && !scope.contains('.'))
+        .collect()
+}
+
+fn generate_access_token() -> String {
+    #[allow(deprecated)]
+    let mut rng = rand::rng();
+    let token: String =
+        (0..64).map(|_| rng.sample(Alphanumeric) as char).collect();
+    format!("gda_{}", token)
+}
+
+impl From<UserTokenModel> for UserAccessToken {
+    fn from(value: UserTokenModel) -> Self {
+        Self {
+            id: value.id,
+            name: value.name,
+            scopes: value
+                .scopes
+                .split('.')
+                .filter(|scope| !scope.is_empty())
+                .map(ToString::to_string)
+                .collect(),
+            expires_at: value.expires_at,
+            is_revoked: value.is_revoked,
+            created_at: value.created_at,
+            updated_at: value.updated_at,
+        }
+    }
+}
diff --git a/lib/service/user/accessibility.rs b/lib/service/user/accessibility.rs
new file mode 100644
index 0000000..5d92601
--- /dev/null
+++ b/lib/service/user/accessibility.rs
@@ -0,0 +1,110 @@
+use db::sqlx;
+use model::users::UserAccessibilityModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserAccessibilityConfig {
+    pub reduce_motion: bool,
+    pub high_contrast: bool,
+    pub screen_reader_optimized: bool,
+    pub font_scale_percent: i32,
+    pub color_blind_mode: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserAccessibilityConfig {
+    pub reduce_motion: Option<bool>,
+    pub high_contrast: Option<bool>,
+    pub screen_reader_optimized: Option<bool>,
+    pub font_scale_percent: Option<i32>,
+    pub color_blind_mode: Option<Option<String>>,
+}
+
+impl AppService {
+    pub async fn user_update_accessibility_config(
+        &self,
+        ctx: &Session,
+        params: UpdateUserAccessibilityConfig,
+    ) -> Result<UserAccessibilityConfig, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut config = self.user_accessibility_config(user_uid).await?;
+        if let Some(reduce_motion) = params.reduce_motion {
+            config.reduce_motion = reduce_motion;
+        }
+        if let Some(high_contrast) = params.high_contrast {
+            config.high_contrast = high_contrast;
+        }
+        if let Some(screen_reader_optimized) = params.screen_reader_optimized {
+            config.screen_reader_optimized = screen_reader_optimized;
+        }
+        if let Some(font_scale_percent) = params.font_scale_percent {
+            config.font_scale_percent = font_scale_percent.clamp(50, 200);
+        }
+        if let Some(color_blind_mode) = params.color_blind_mode {
+            config.color_blind_mode = color_blind_mode;
+        }
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO user_accessibility \
+                (\"user\", reduce_motion, high_contrast, screen_reader_optimized, font_scale_percent, color_blind_mode, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $7) \
+             ON CONFLICT (\"user\") DO UPDATE SET \
+                reduce_motion = EXCLUDED.reduce_motion, high_contrast = EXCLUDED.high_contrast, \
+                screen_reader_optimized = EXCLUDED.screen_reader_optimized, font_scale_percent = EXCLUDED.font_scale_percent, \
+                color_blind_mode = EXCLUDED.color_blind_mode, updated_at = EXCLUDED.updated_at",
+        )
+        .bind(user_uid)
+        .bind(config.reduce_motion)
+        .bind(config.high_contrast)
+        .bind(config.screen_reader_optimized)
+        .bind(config.font_scale_percent)
+        .bind(&config.color_blind_mode)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(config)
+    }
+
+    pub(crate) async fn user_accessibility_config(
+        &self,
+        user_uid: uuid::Uuid,
+    ) -> Result<UserAccessibilityConfig, AppError> {
+        let row = sqlx::query_as::<_, UserAccessibilityModel>(
+            "SELECT \"user\", reduce_motion, high_contrast, screen_reader_optimized, font_scale_percent, color_blind_mode, created_at, updated_at \
+             FROM user_accessibility WHERE \"user\" = $1",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(row.map(Into::into).unwrap_or_default())
+    }
+}
+
+impl Default for UserAccessibilityConfig {
+    fn default() -> Self {
+        Self {
+            reduce_motion: false,
+            high_contrast: false,
+            screen_reader_optimized: false,
+            font_scale_percent: 100,
+            color_blind_mode: None,
+        }
+    }
+}
+
+impl From<UserAccessibilityModel> for UserAccessibilityConfig {
+    fn from(value: UserAccessibilityModel) -> Self {
+        Self {
+            reduce_motion: value.reduce_motion,
+            high_contrast: value.high_contrast,
+            screen_reader_optimized: value.screen_reader_optimized,
+            font_scale_percent: value.font_scale_percent,
+            color_blind_mode: value.color_blind_mode,
+        }
+    }
+}
diff --git a/lib/service/user/appearance.rs b/lib/service/user/appearance.rs
new file mode 100644
index 0000000..d33a5b2
--- /dev/null
+++ b/lib/service/user/appearance.rs
@@ -0,0 +1,110 @@
+use db::sqlx;
+use model::users::UserAppearanceModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserAppearanceConfig {
+    pub theme: String,
+    pub code_theme: String,
+    pub layout_density: String,
+    pub sidebar_collapsed: bool,
+    pub show_line_numbers: bool,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserAppearanceConfig {
+    pub theme: Option<String>,
+    pub code_theme: Option<String>,
+    pub layout_density: Option<String>,
+    pub sidebar_collapsed: Option<bool>,
+    pub show_line_numbers: Option<bool>,
+}
+
+impl AppService {
+    pub async fn user_update_appearance_config(
+        &self,
+        ctx: &Session,
+        params: UpdateUserAppearanceConfig,
+    ) -> Result<UserAppearanceConfig, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut config = self.user_appearance_config(user_uid).await?;
+        if let Some(theme) = params.theme {
+            config.theme = theme;
+        }
+        if let Some(code_theme) = params.code_theme {
+            config.code_theme = code_theme;
+        }
+        if let Some(layout_density) = params.layout_density {
+            config.layout_density = layout_density;
+        }
+        if let Some(sidebar_collapsed) = params.sidebar_collapsed {
+            config.sidebar_collapsed = sidebar_collapsed;
+        }
+        if let Some(show_line_numbers) = params.show_line_numbers {
+            config.show_line_numbers = show_line_numbers;
+        }
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO user_appearance \
+                (\"user\", theme, code_theme, layout_density, sidebar_collapsed, show_line_numbers, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $7) \
+             ON CONFLICT (\"user\") DO UPDATE SET \
+                theme = EXCLUDED.theme, code_theme = EXCLUDED.code_theme, layout_density = EXCLUDED.layout_density, \
+                sidebar_collapsed = EXCLUDED.sidebar_collapsed, show_line_numbers = EXCLUDED.show_line_numbers, \
+                updated_at = EXCLUDED.updated_at",
+        )
+        .bind(user_uid)
+        .bind(&config.theme)
+        .bind(&config.code_theme)
+        .bind(&config.layout_density)
+        .bind(config.sidebar_collapsed)
+        .bind(config.show_line_numbers)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(config)
+    }
+
+    pub(crate) async fn user_appearance_config(
+        &self,
+        user_uid: uuid::Uuid,
+    ) -> Result<UserAppearanceConfig, AppError> {
+        let row = sqlx::query_as::<_, UserAppearanceModel>(
+            "SELECT \"user\", theme, code_theme, layout_density, sidebar_collapsed, show_line_numbers, created_at, updated_at \
+             FROM user_appearance WHERE \"user\" = $1",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(row.map(Into::into).unwrap_or_default())
+    }
+}
+
+impl Default for UserAppearanceConfig {
+    fn default() -> Self {
+        Self {
+            theme: "system".to_string(),
+            code_theme: "github-dark".to_string(),
+            layout_density: "comfortable".to_string(),
+            sidebar_collapsed: false,
+            show_line_numbers: true,
+        }
+    }
+}
+
+impl From<UserAppearanceModel> for UserAppearanceConfig {
+    fn from(value: UserAppearanceModel) -> Self {
+        Self {
+            theme: value.theme,
+            code_theme: value.code_theme,
+            layout_density: value.layout_density,
+            sidebar_collapsed: value.sidebar_collapsed,
+            show_line_numbers: value.show_line_numbers,
+        }
+    }
+}
diff --git a/lib/service/user/chpc.rs b/lib/service/user/chpc.rs
new file mode 100644
index 0000000..1771fdf
--- /dev/null
+++ b/lib/service/user/chpc.rs
@@ -0,0 +1,187 @@
+use std::collections::HashMap;
+
+use chrono::{Duration, NaiveDate, Utc};
+use db::sqlx;
+use serde::{Deserialize, Serialize};
+use session::Session;
+use utoipa::{IntoParams, ToSchema};
+
+use crate::{AppService, error::AppError};
+
+const HEATMAP_CACHE_PREFIX: &str = "user:heatmap";
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ContributionHeatmapItem {
+    pub date: String,
+    pub count: i32,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ContributionHeatmapResponse {
+    pub username: String,
+    pub total_contributions: i64,
+    pub heatmap: Vec<ContributionHeatmapItem>,
+    pub start_date: String,
+    pub end_date: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, IntoParams)]
+pub struct ContributionHeatmapQuery {
+    pub start_date: Option<String>,
+    pub end_date: Option<String>,
+}
+
+impl AppService {
+    pub async fn user_chpc(
+        &self,
+        ctx: &Session,
+        query: ContributionHeatmapQuery,
+    ) -> Result<ContributionHeatmapResponse, AppError> {
+        let user_uid = ctx.user().ok_or(AppError::Unauthorized)?;
+        let user = self.auth_find_user_by_uid(user_uid).await?;
+        self.user_contribution_heatmap_for_user(user.id, user.username, query)
+            .await
+    }
+
+    pub(crate) async fn user_contribution_heatmap_for_user(
+        &self,
+        user_uid: uuid::Uuid,
+        username: String,
+        query: ContributionHeatmapQuery,
+    ) -> Result<ContributionHeatmapResponse, AppError> {
+        let (start_date, end_date) =
+            parse_date_range(query.start_date, query.end_date)?;
+        let cache_key = build_heatmap_cache_key(user_uid, start_date, end_date);
+
+        if let Ok(Some(cached)) = self
+            .cache
+            .get::<ContributionHeatmapResponse>(&cache_key)
+            .await
+        {
+            return Ok(cached);
+        }
+
+        let start_dt = start_date
+            .and_hms_opt(0, 0, 0)
+            .ok_or(AppError::InternalError)?
+            .and_utc();
+        let end_dt = end_date
+            .and_hms_opt(23, 59, 59)
+            .ok_or(AppError::InternalError)?
+            .and_utc();
+
+        let rows = sqlx::query_as::<_, (chrono::DateTime<Utc>,)>(
+            "SELECT created_at FROM repo_commit \
+             WHERE (author = $1 OR committer = $1) AND created_at >= $2 AND created_at <= $3",
+        )
+        .bind(user_uid)
+        .bind(start_dt)
+        .bind(end_dt)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let mut sparse = HashMap::<String, i64>::new();
+        for (created_at,) in &rows {
+            let date = created_at.format("%Y-%m-%d").to_string();
+            *sparse.entry(date).or_insert(0) += 1;
+        }
+
+        let mut heatmap = Vec::new();
+        let mut current = start_date;
+        while current <= end_date {
+            let date = current.format("%Y-%m-%d").to_string();
+            let count = sparse.get(&date).copied().unwrap_or(0) as i32;
+            heatmap.push(ContributionHeatmapItem { date, count });
+            current += Duration::days(1);
+        }
+
+        let response = ContributionHeatmapResponse {
+            username,
+            total_contributions: rows.len() as i64,
+            heatmap,
+            start_date: start_date.format("%Y-%m-%d").to_string(),
+            end_date: end_date.format("%Y-%m-%d").to_string(),
+        };
+
+        self.cache
+            .set(&cache_key, &response)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+
+        Ok(response)
+    }
+
+    pub async fn user_invalidate_chpc_cache(
+        &self,
+        ctx: &Session,
+    ) -> Result<(), AppError> {
+        let user_uid = ctx.user().ok_or(AppError::Unauthorized)?;
+        self.invalidate_user_heatmap_cache(user_uid).await
+    }
+
+    pub(crate) async fn invalidate_user_heatmap_cache(
+        &self,
+        user_uid: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        let pattern = format!("{}:{}:*", HEATMAP_CACHE_PREFIX, user_uid);
+        self.cache
+            .delete_pattern(&pattern)
+            .await
+            .map_err(|e| AppError::InternalServerError(e.to_string()))?;
+        Ok(())
+    }
+}
+
+fn build_heatmap_cache_key(
+    user_uid: uuid::Uuid,
+    start_date: NaiveDate,
+    end_date: NaiveDate,
+) -> String {
+    format!(
+        "{}:{}:{}:{}",
+        HEATMAP_CACHE_PREFIX,
+        user_uid,
+        start_date.format("%Y-%m-%d"),
+        end_date.format("%Y-%m-%d"),
+    )
+}
+
+fn parse_date_range(
+    start_date_str: Option<String>,
+    end_date_str: Option<String>,
+) -> Result<(NaiveDate, NaiveDate), AppError> {
+    let today = Utc::now().date_naive();
+    let one_year_ago = today - Duration::days(365);
+
+    let start_date = match start_date_str {
+        Some(date) => parse_date(&date, "start_date")?,
+        None => one_year_ago,
+    };
+    let end_date = match end_date_str {
+        Some(date) => parse_date(&date, "end_date")?,
+        None => today,
+    };
+
+    if start_date > end_date {
+        return Err(AppError::BadRequest(
+            "start_date cannot be later than end_date".to_string(),
+        ));
+    }
+
+    if (end_date - start_date).num_days() > 730 {
+        return Err(AppError::BadRequest(
+            "date range cannot exceed 2 years".to_string(),
+        ));
+    }
+
+    Ok((start_date, end_date))
+}
+
+fn parse_date(value: &str, field: &str) -> Result<NaiveDate, AppError> {
+    NaiveDate::parse_from_str(value, "%Y-%m-%d").map_err(|_| {
+        AppError::BadRequest(format!(
+            "invalid {field} format, expected YYYY-MM-DD"
+        ))
+    })
+}
diff --git a/lib/service/user/config.rs b/lib/service/user/config.rs
new file mode 100644
index 0000000..67bc809
--- /dev/null
+++ b/lib/service/user/config.rs
@@ -0,0 +1,34 @@
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use super::{
+    accessibility::UserAccessibilityConfig, appearance::UserAppearanceConfig,
+    notification::UserNotificationConfig, privacy::UserPrivacyConfig,
+    profile::UserProfileConfig,
+};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserConfigResponse {
+    pub profile: UserProfileConfig,
+    pub appearance: UserAppearanceConfig,
+    pub accessibility: UserAccessibilityConfig,
+    pub privacy: UserPrivacyConfig,
+    pub notifications: UserNotificationConfig,
+}
+
+impl AppService {
+    pub async fn user_config(
+        &self,
+        ctx: &Session,
+    ) -> Result<UserConfigResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        Ok(UserConfigResponse {
+            profile: self.user_profile_config(user_uid).await?,
+            appearance: self.user_appearance_config(user_uid).await?,
+            accessibility: self.user_accessibility_config(user_uid).await?,
+            privacy: self.user_privacy_config(user_uid).await?,
+            notifications: self.user_notification_config(user_uid).await?,
+        })
+    }
+}
diff --git a/lib/service/user/mod.rs b/lib/service/user/mod.rs
new file mode 100644
index 0000000..e9d915a
--- /dev/null
+++ b/lib/service/user/mod.rs
@@ -0,0 +1,9 @@
+pub mod access_token;
+pub mod accessibility;
+pub mod appearance;
+pub mod chpc;
+pub mod config;
+pub mod notification;
+pub mod privacy;
+pub mod profile;
+pub mod sshkey;
diff --git a/lib/service/user/notification.rs b/lib/service/user/notification.rs
new file mode 100644
index 0000000..5cdf8e6
--- /dev/null
+++ b/lib/service/user/notification.rs
@@ -0,0 +1,252 @@
+use db::sqlx;
+use model::notify::UserAppNotifyModel;
+use model::users::UserNotificationModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserNotificationConfig {
+    pub email_enabled: bool,
+    pub in_app_enabled: bool,
+    pub push_enabled: bool,
+    pub digest_mode: String,
+    pub dnd_enabled: bool,
+    pub dnd_start_minute: Option<i32>,
+    pub dnd_end_minute: Option<i32>,
+    pub marketing_enabled: bool,
+    pub security_enabled: bool,
+    pub product_enabled: bool,
+    pub push_subscription_endpoint: Option<String>,
+    pub push_subscription_keys_p256dh: Option<String>,
+    pub push_subscription_keys_auth: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct AppNotificationItem {
+    pub id: uuid::Uuid,
+    pub title: String,
+    pub body: String,
+    pub notify_type: String,
+    #[schema(value_type = Option<String>)]
+    pub read_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl From<UserAppNotifyModel> for AppNotificationItem {
+    fn from(n: UserAppNotifyModel) -> Self {
+        Self {
+            id: n.id,
+            title: n.title,
+            body: n.body,
+            notify_type: n.notify_type,
+            read_at: n.read_at,
+            created_at: n.created_at,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserNotificationConfig {
+    pub email_enabled: Option<bool>,
+    pub in_app_enabled: Option<bool>,
+    pub push_enabled: Option<bool>,
+    pub digest_mode: Option<String>,
+    pub dnd_enabled: Option<bool>,
+    pub dnd_start_minute: Option<Option<i32>>,
+    pub dnd_end_minute: Option<Option<i32>>,
+    pub marketing_enabled: Option<bool>,
+    pub security_enabled: Option<bool>,
+    pub product_enabled: Option<bool>,
+    pub push_subscription_endpoint: Option<Option<String>>,
+    pub push_subscription_keys_p256dh: Option<Option<String>>,
+    pub push_subscription_keys_auth: Option<Option<String>>,
+}
+
+impl AppService {
+    pub async fn user_update_notification_config(
+        &self,
+        ctx: &Session,
+        params: UpdateUserNotificationConfig,
+    ) -> Result<UserNotificationConfig, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut config = self.user_notification_config(user_uid).await?;
+        if let Some(email_enabled) = params.email_enabled {
+            config.email_enabled = email_enabled;
+        }
+        if let Some(in_app_enabled) = params.in_app_enabled {
+            config.in_app_enabled = in_app_enabled;
+        }
+        if let Some(push_enabled) = params.push_enabled {
+            config.push_enabled = push_enabled;
+        }
+        if let Some(digest_mode) = params.digest_mode {
+            config.digest_mode = digest_mode;
+        }
+        if let Some(dnd_enabled) = params.dnd_enabled {
+            config.dnd_enabled = dnd_enabled;
+        }
+        if let Some(dnd_start_minute) = params.dnd_start_minute {
+            config.dnd_start_minute = dnd_start_minute;
+        }
+        if let Some(dnd_end_minute) = params.dnd_end_minute {
+            config.dnd_end_minute = dnd_end_minute;
+        }
+        if let Some(marketing_enabled) = params.marketing_enabled {
+            config.marketing_enabled = marketing_enabled;
+        }
+        if let Some(security_enabled) = params.security_enabled {
+            config.security_enabled = security_enabled;
+        }
+        if let Some(product_enabled) = params.product_enabled {
+            config.product_enabled = product_enabled;
+        }
+        if let Some(push_subscription_endpoint) =
+            params.push_subscription_endpoint
+        {
+            config.push_subscription_endpoint = push_subscription_endpoint;
+        }
+        if let Some(push_subscription_keys_p256dh) =
+            params.push_subscription_keys_p256dh
+        {
+            config.push_subscription_keys_p256dh =
+                push_subscription_keys_p256dh;
+        }
+        if let Some(push_subscription_keys_auth) =
+            params.push_subscription_keys_auth
+        {
+            config.push_subscription_keys_auth = push_subscription_keys_auth;
+        }
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO user_notification \
+                (\"user\", email_enabled, in_app_enabled, push_enabled, digest_mode, dnd_enabled, dnd_start_minute, dnd_end_minute, \
+                 marketing_enabled, security_enabled, product_enabled, push_subscription_endpoint, push_subscription_keys_p256dh, \
+                 push_subscription_keys_auth, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $15) \
+             ON CONFLICT (\"user\") DO UPDATE SET \
+                email_enabled = EXCLUDED.email_enabled, in_app_enabled = EXCLUDED.in_app_enabled, push_enabled = EXCLUDED.push_enabled, \
+                digest_mode = EXCLUDED.digest_mode, dnd_enabled = EXCLUDED.dnd_enabled, dnd_start_minute = EXCLUDED.dnd_start_minute, \
+                dnd_end_minute = EXCLUDED.dnd_end_minute, marketing_enabled = EXCLUDED.marketing_enabled, security_enabled = EXCLUDED.security_enabled, \
+                product_enabled = EXCLUDED.product_enabled, push_subscription_endpoint = EXCLUDED.push_subscription_endpoint, \
+                push_subscription_keys_p256dh = EXCLUDED.push_subscription_keys_p256dh, push_subscription_keys_auth = EXCLUDED.push_subscription_keys_auth, \
+                updated_at = EXCLUDED.updated_at",
+        )
+        .bind(user_uid)
+        .bind(config.email_enabled)
+        .bind(config.in_app_enabled)
+        .bind(config.push_enabled)
+        .bind(&config.digest_mode)
+        .bind(config.dnd_enabled)
+        .bind(config.dnd_start_minute)
+        .bind(config.dnd_end_minute)
+        .bind(config.marketing_enabled)
+        .bind(config.security_enabled)
+        .bind(config.product_enabled)
+        .bind(&config.push_subscription_endpoint)
+        .bind(&config.push_subscription_keys_p256dh)
+        .bind(&config.push_subscription_keys_auth)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(config)
+    }
+
+    pub async fn list_notifications(
+        &self,
+        ctx: &Session,
+        pagination: Pagination,
+    ) -> Result<Vec<AppNotificationItem>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let rows = sqlx::query_as::<_, UserAppNotifyModel>(
+            "SELECT id, \"user\", title, body, notify_type, target_type, target_id, metadata, read_at, archived_at, created_at, updated_at \
+             FROM user_app_notify WHERE \"user\" = $1 AND archived_at IS NULL \
+             ORDER BY created_at DESC \
+             OFFSET $2 LIMIT $3",
+        )
+        .bind(user_uid)
+        .bind(pagination.offset() as i64)
+        .bind(pagination.limit() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    pub(crate) async fn unread_notifications_count(
+        &self,
+        user_uid: uuid::Uuid,
+    ) -> Result<i64, AppError> {
+        let row: (Option<i64>,) = sqlx::query_as(
+            "SELECT COUNT(*) FROM user_app_notify \
+             WHERE \"user\" = $1 AND read_at IS NULL AND archived_at IS NULL",
+        )
+        .bind(user_uid)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.0.unwrap_or(0))
+    }
+
+    pub(crate) async fn user_notification_config(
+        &self,
+        user_uid: uuid::Uuid,
+    ) -> Result<UserNotificationConfig, AppError> {
+        let row = sqlx::query_as::<_, UserNotificationModel>(
+            "SELECT \"user\", email_enabled, in_app_enabled, push_enabled, digest_mode, dnd_enabled, dnd_start_minute, dnd_end_minute, \
+                    marketing_enabled, security_enabled, product_enabled, push_subscription_endpoint, push_subscription_keys_p256dh, \
+                    push_subscription_keys_auth, created_at, updated_at \
+             FROM user_notification WHERE \"user\" = $1",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(row.map(Into::into).unwrap_or_default())
+    }
+}
+
+impl Default for UserNotificationConfig {
+    fn default() -> Self {
+        Self {
+            email_enabled: true,
+            in_app_enabled: true,
+            push_enabled: false,
+            digest_mode: "daily".to_string(),
+            dnd_enabled: false,
+            dnd_start_minute: None,
+            dnd_end_minute: None,
+            marketing_enabled: false,
+            security_enabled: true,
+            product_enabled: true,
+            push_subscription_endpoint: None,
+            push_subscription_keys_p256dh: None,
+            push_subscription_keys_auth: None,
+        }
+    }
+}
+
+impl From<UserNotificationModel> for UserNotificationConfig {
+    fn from(value: UserNotificationModel) -> Self {
+        Self {
+            email_enabled: value.email_enabled,
+            in_app_enabled: value.in_app_enabled,
+            push_enabled: value.push_enabled,
+            digest_mode: value.digest_mode,
+            dnd_enabled: value.dnd_enabled,
+            dnd_start_minute: value.dnd_start_minute,
+            dnd_end_minute: value.dnd_end_minute,
+            marketing_enabled: value.marketing_enabled,
+            security_enabled: value.security_enabled,
+            product_enabled: value.product_enabled,
+            push_subscription_endpoint: value.push_subscription_endpoint,
+            push_subscription_keys_p256dh: value.push_subscription_keys_p256dh,
+            push_subscription_keys_auth: value.push_subscription_keys_auth,
+        }
+    }
+}
diff --git a/lib/service/user/privacy.rs b/lib/service/user/privacy.rs
new file mode 100644
index 0000000..86a9564
--- /dev/null
+++ b/lib/service/user/privacy.rs
@@ -0,0 +1,119 @@
+use db::sqlx;
+use model::users::UserPrivacyModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserPrivacyConfig {
+    pub profile_visibility: String,
+    pub email_visibility: String,
+    pub activity_visibility: String,
+    pub allow_search_indexing: bool,
+    pub allow_direct_messages: bool,
+    pub show_online_status: bool,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserPrivacyConfig {
+    pub profile_visibility: Option<String>,
+    pub email_visibility: Option<String>,
+    pub activity_visibility: Option<String>,
+    pub allow_search_indexing: Option<bool>,
+    pub allow_direct_messages: Option<bool>,
+    pub show_online_status: Option<bool>,
+}
+
+impl AppService {
+    pub async fn user_update_privacy_config(
+        &self,
+        ctx: &Session,
+        params: UpdateUserPrivacyConfig,
+    ) -> Result<UserPrivacyConfig, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut config = self.user_privacy_config(user_uid).await?;
+        if let Some(profile_visibility) = params.profile_visibility {
+            config.profile_visibility = profile_visibility;
+        }
+        if let Some(email_visibility) = params.email_visibility {
+            config.email_visibility = email_visibility;
+        }
+        if let Some(activity_visibility) = params.activity_visibility {
+            config.activity_visibility = activity_visibility;
+        }
+        if let Some(allow_search_indexing) = params.allow_search_indexing {
+            config.allow_search_indexing = allow_search_indexing;
+        }
+        if let Some(allow_direct_messages) = params.allow_direct_messages {
+            config.allow_direct_messages = allow_direct_messages;
+        }
+        if let Some(show_online_status) = params.show_online_status {
+            config.show_online_status = show_online_status;
+        }
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO user_privacy \
+                (\"user\", profile_visibility, email_visibility, activity_visibility, allow_search_indexing, allow_direct_messages, show_online_status, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $8) \
+             ON CONFLICT (\"user\") DO UPDATE SET \
+                profile_visibility = EXCLUDED.profile_visibility, email_visibility = EXCLUDED.email_visibility, \
+                activity_visibility = EXCLUDED.activity_visibility, allow_search_indexing = EXCLUDED.allow_search_indexing, \
+                allow_direct_messages = EXCLUDED.allow_direct_messages, show_online_status = EXCLUDED.show_online_status, \
+                updated_at = EXCLUDED.updated_at",
+        )
+        .bind(user_uid)
+        .bind(&config.profile_visibility)
+        .bind(&config.email_visibility)
+        .bind(&config.activity_visibility)
+        .bind(config.allow_search_indexing)
+        .bind(config.allow_direct_messages)
+        .bind(config.show_online_status)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(config)
+    }
+
+    pub(crate) async fn user_privacy_config(
+        &self,
+        user_uid: uuid::Uuid,
+    ) -> Result<UserPrivacyConfig, AppError> {
+        let row = sqlx::query_as::<_, UserPrivacyModel>(
+            "SELECT \"user\", profile_visibility, email_visibility, activity_visibility, allow_search_indexing, allow_direct_messages, show_online_status, created_at, updated_at \
+             FROM user_privacy WHERE \"user\" = $1",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(row.map(Into::into).unwrap_or_default())
+    }
+}
+
+impl Default for UserPrivacyConfig {
+    fn default() -> Self {
+        Self {
+            profile_visibility: "public".to_string(),
+            email_visibility: "private".to_string(),
+            activity_visibility: "public".to_string(),
+            allow_search_indexing: true,
+            allow_direct_messages: true,
+            show_online_status: true,
+        }
+    }
+}
+
+impl From<UserPrivacyModel> for UserPrivacyConfig {
+    fn from(value: UserPrivacyModel) -> Self {
+        Self {
+            profile_visibility: value.profile_visibility,
+            email_visibility: value.email_visibility,
+            activity_visibility: value.activity_visibility,
+            allow_search_indexing: value.allow_search_indexing,
+            allow_direct_messages: value.allow_direct_messages,
+            show_online_status: value.show_online_status,
+        }
+    }
+}
diff --git a/lib/service/user/profile.rs b/lib/service/user/profile.rs
new file mode 100644
index 0000000..bff7f3c
--- /dev/null
+++ b/lib/service/user/profile.rs
@@ -0,0 +1,182 @@
+use db::sqlx;
+use model::users::UserProfileModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+use storage::{ObjectStorage, PutObjectOptions};
+use uuid::Uuid;
+
+use crate::{AppService, error::AppError, session_user};
+
+/// Allowed image MIME types for avatars.
+const ALLOWED_AVATAR_TYPES: &[&str] = &[
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+];
+
+/// Maximum avatar file size: 5 MB.
+const MAX_AVATAR_SIZE: usize = 5 * 1024 * 1024;
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserProfileConfig {
+    pub language: String,
+    pub theme: String,
+    pub timezone: String,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserProfileConfig {
+    pub language: Option<String>,
+    pub theme: Option<String>,
+    pub timezone: Option<String>,
+    pub avatar_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, utoipa::ToSchema)]
+pub struct AvatarUploadResponse {
+    pub avatar_url: String,
+}
+
+/// Derive file extension from MIME content type.
+fn extension_from_content_type(content_type: &str) -> &str {
+    match content_type {
+        "image/png" => "png",
+        "image/jpeg" => "jpg",
+        "image/webp" => "webp",
+        "image/gif" => "gif",
+        _ => "bin",
+    }
+}
+
+impl AppService {
+    pub async fn user_update_profile_config(
+        &self,
+        ctx: &Session,
+        params: UpdateUserProfileConfig,
+    ) -> Result<UserProfileConfig, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut config = self.user_profile_config(user_uid).await?;
+        if let Some(language) = params.language {
+            config.language = language;
+        }
+        if let Some(theme) = params.theme {
+            config.theme = theme;
+        }
+        if let Some(timezone) = params.timezone {
+            config.timezone = timezone;
+        }
+        if let Some(avatar_url) = params.avatar_url {
+            sqlx::query("UPDATE users SET avatar_url = $1 WHERE id = $2")
+                .bind(&avatar_url)
+                .bind(user_uid)
+                .execute(self.db.writer())
+                .await
+                .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO user_profile (\"user\", language, theme, timezone, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $5) \
+             ON CONFLICT (\"user\") DO UPDATE SET \
+                language = EXCLUDED.language, theme = EXCLUDED.theme, timezone = EXCLUDED.timezone, updated_at = EXCLUDED.updated_at",
+        )
+        .bind(user_uid)
+        .bind(&config.language)
+        .bind(&config.theme)
+        .bind(&config.timezone)
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(config)
+    }
+
+    /// Upload a user avatar image, store it, and update the user's avatar_url.
+    pub async fn user_upload_avatar(
+        &self,
+        ctx: &Session,
+        bytes: Vec<u8>,
+        content_type: &str,
+    ) -> Result<AvatarUploadResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+
+        if bytes.len() > MAX_AVATAR_SIZE {
+            return Err(AppError::AvatarUploadError(
+                "file size exceeds 5 MB limit".to_string(),
+            ));
+        }
+        if !ALLOWED_AVATAR_TYPES.contains(&content_type) {
+            return Err(AppError::AvatarUploadError(format!(
+                "unsupported image type: {content_type}. Allowed: png, jpeg, webp, gif"
+            )));
+        }
+
+        let ext = extension_from_content_type(content_type);
+        let key = format!(
+            "avatars/users/{user_uid}-{}.{ext}",
+            uuid::Uuid::now_v7()
+        );
+
+        let stored = self
+            .storage
+            .put_bytes(
+                &key,
+                bytes,
+                PutObjectOptions {
+                    content_type: Some(content_type.to_string()),
+                    ..PutObjectOptions::default()
+                },
+            )
+            .await
+            .map_err(|e| {
+                AppError::AvatarUploadError(format!("storage error: {e}"))
+            })?;
+
+        sqlx::query("UPDATE users SET avatar_url = $1 WHERE id = $2")
+            .bind(&stored.url)
+            .bind(user_uid)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(AvatarUploadResponse {
+            avatar_url: stored.url,
+        })
+    }
+
+    pub(crate) async fn user_profile_config(
+        &self,
+        user_uid: Uuid,
+    ) -> Result<UserProfileConfig, AppError> {
+        let row = sqlx::query_as::<_, UserProfileModel>(
+            "SELECT \"user\", language, theme, timezone, created_at, updated_at \
+             FROM user_profile WHERE \"user\" = $1",
+        )
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(row.map(Into::into).unwrap_or_default())
+    }
+}
+
+impl Default for UserProfileConfig {
+    fn default() -> Self {
+        Self {
+            language: "en".to_string(),
+            theme: "system".to_string(),
+            timezone: "UTC".to_string(),
+        }
+    }
+}
+
+impl From<UserProfileModel> for UserProfileConfig {
+    fn from(value: UserProfileModel) -> Self {
+        Self {
+            language: value.language,
+            theme: value.theme,
+            timezone: value.timezone,
+        }
+    }
+}
diff --git a/lib/service/user/sshkey.rs b/lib/service/user/sshkey.rs
new file mode 100644
index 0000000..9163400
--- /dev/null
+++ b/lib/service/user/sshkey.rs
@@ -0,0 +1,248 @@
+use base64::{Engine as _, engine::general_purpose};
+use db::sqlx;
+use model::users::UserSshKeyModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+use sha2::{Digest, Sha256};
+
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserSshKey {
+    pub id: i64,
+    pub title: String,
+    pub public_key: String,
+    pub fingerprint: String,
+    pub key_type: String,
+    pub key_bits: Option<i32>,
+    pub is_verified: bool,
+    #[schema(value_type = Option<String>)]
+    pub last_used_at: Option<chrono::DateTime<chrono::Utc>>,
+    #[schema(value_type = Option<String>)]
+    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
+    pub is_revoked: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateUserSshKey {
+    pub title: String,
+    pub public_key: String,
+    #[schema(value_type = Option<String>)]
+    pub expires_at: Option<chrono::DateTime<chrono::Utc>>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateUserSshKey {
+    pub title: Option<String>,
+    #[schema(value_type = Option<String>)]
+    pub expires_at: Option<Option<chrono::DateTime<chrono::Utc>>>,
+}
+
+impl AppService {
+    pub async fn user_ssh_keys(
+        &self,
+        ctx: &Session,
+    ) -> Result<Vec<UserSshKey>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let rows = sqlx::query_as::<_, UserSshKeyModel>(
+            "SELECT id, \"user\", title, public_key, fingerprint, key_type, key_bits, is_verified, last_used_at, expires_at, is_revoked, created_at, updated_at \
+             FROM user_ssh_key WHERE \"user\" = $1 ORDER BY created_at DESC",
+        )
+        .bind(user_uid)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(Into::into).collect())
+    }
+
+    pub async fn user_add_ssh_key(
+        &self,
+        ctx: &Session,
+        params: CreateUserSshKey,
+    ) -> Result<UserSshKey, AppError> {
+        let user_uid = session_user(ctx)?;
+        let title = params.title.trim();
+        if title.is_empty() {
+            return Err(AppError::BadRequest(
+                "ssh key title is required".to_string(),
+            ));
+        }
+
+        let parsed = parse_public_key(&params.public_key)?;
+        let now = chrono::Utc::now();
+        let row = sqlx::query_as::<_, UserSshKeyModel>(
+            "INSERT INTO user_ssh_key \
+                (\"user\", title, public_key, fingerprint, key_type, key_bits, is_verified, last_used_at, expires_at, is_revoked, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, true, NULL, $7, false, $8, $8) \
+             RETURNING id, \"user\", title, public_key, fingerprint, key_type, key_bits, is_verified, last_used_at, expires_at, is_revoked, created_at, updated_at",
+        )
+        .bind(user_uid)
+        .bind(title)
+        .bind(parsed.public_key)
+        .bind(parsed.fingerprint)
+        .bind(parsed.key_type)
+        .bind(parsed.key_bits)
+        .bind(params.expires_at)
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(row.into())
+    }
+
+    pub async fn user_revoke_ssh_key(
+        &self,
+        ctx: &Session,
+        key_id: i64,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let affected = sqlx::query(
+            "UPDATE user_ssh_key SET is_revoked = true, updated_at = $1 \
+             WHERE id = $2 AND \"user\" = $3 AND is_revoked = false",
+        )
+        .bind(chrono::Utc::now())
+        .bind(key_id)
+        .bind(user_uid)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .rows_affected();
+
+        if affected == 0 {
+            return Err(AppError::NotFound("ssh key not found".to_string()));
+        }
+        Ok(())
+    }
+
+    pub async fn user_update_ssh_key(
+        &self,
+        ctx: &Session,
+        key_id: i64,
+        params: UpdateUserSshKey,
+    ) -> Result<UserSshKey, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut key = self.user_ssh_key_by_id(user_uid, key_id).await?;
+
+        if let Some(title) = params.title {
+            let title = title.trim();
+            if title.is_empty() {
+                return Err(AppError::BadRequest(
+                    "ssh key title is required".to_string(),
+                ));
+            }
+            key.title = title.to_string();
+        }
+        if let Some(expires_at) = params.expires_at {
+            key.expires_at = expires_at;
+        }
+
+        let row = sqlx::query_as::<_, UserSshKeyModel>(
+            "UPDATE user_ssh_key SET title = $1, expires_at = $2, updated_at = $3 \
+             WHERE id = $4 AND \"user\" = $5 AND is_revoked = false \
+             RETURNING id, \"user\", title, public_key, fingerprint, key_type, key_bits, is_verified, last_used_at, expires_at, is_revoked, created_at, updated_at",
+        )
+        .bind(&key.title)
+        .bind(key.expires_at)
+        .bind(chrono::Utc::now())
+        .bind(key_id)
+        .bind(user_uid)
+        .fetch_optional(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or_else(|| AppError::NotFound("ssh key not found".to_string()))?;
+
+        Ok(row.into())
+    }
+
+    async fn user_ssh_key_by_id(
+        &self,
+        user_uid: uuid::Uuid,
+        key_id: i64,
+    ) -> Result<UserSshKey, AppError> {
+        sqlx::query_as::<_, UserSshKeyModel>(
+            "SELECT id, \"user\", title, public_key, fingerprint, key_type, key_bits, is_verified, last_used_at, expires_at, is_revoked, created_at, updated_at \
+             FROM user_ssh_key WHERE id = $1 AND \"user\" = $2 AND is_revoked = false",
+        )
+        .bind(key_id)
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .map(Into::into)
+        .ok_or_else(|| AppError::NotFound("ssh key not found".to_string()))
+    }
+}
+
+struct ParsedPublicKey {
+    public_key: String,
+    fingerprint: String,
+    key_type: String,
+    key_bits: Option<i32>,
+}
+
+fn parse_public_key(public_key: &str) -> Result<ParsedPublicKey, AppError> {
+    let public_key = public_key.trim();
+    let mut parts = public_key.split_whitespace();
+    let key_type = parts.next().ok_or_else(|| {
+        AppError::BadRequest("invalid ssh public key".to_string())
+    })?;
+    let key_data_base64 = parts.next().ok_or_else(|| {
+        AppError::BadRequest("invalid ssh public key".to_string())
+    })?;
+
+    let key_data =
+        general_purpose::STANDARD
+            .decode(key_data_base64)
+            .map_err(|_| {
+                AppError::BadRequest("invalid ssh public key".to_string())
+            })?;
+
+    let mut hasher = Sha256::new();
+    hasher.update(&key_data);
+    let fingerprint = format!(
+        "SHA256:{}",
+        general_purpose::STANDARD_NO_PAD.encode(hasher.finalize())
+    );
+
+    Ok(ParsedPublicKey {
+        public_key: public_key.to_string(),
+        fingerprint,
+        key_type: key_type.to_string(),
+        key_bits: key_bits(key_type),
+    })
+}
+
+fn key_bits(key_type: &str) -> Option<i32> {
+    match key_type {
+        "ssh-ed25519" => Some(256),
+        "ecdsa-sha2-nistp256" => Some(256),
+        "ecdsa-sha2-nistp384" => Some(384),
+        "ecdsa-sha2-nistp521" => Some(521),
+        _ => None,
+    }
+}
+
+impl From<UserSshKeyModel> for UserSshKey {
+    fn from(value: UserSshKeyModel) -> Self {
+        Self {
+            id: value.id,
+            title: value.title,
+            public_key: value.public_key,
+            fingerprint: value.fingerprint,
+            key_type: value.key_type,
+            key_bits: value.key_bits,
+            is_verified: value.is_verified,
+            last_used_at: value.last_used_at,
+            expires_at: value.expires_at,
+            is_revoked: value.is_revoked,
+            created_at: value.created_at,
+            updated_at: value.updated_at,
+        }
+    }
+}
diff --git a/lib/service/users/chpc.rs b/lib/service/users/chpc.rs
new file mode 100644
index 0000000..4e0b162
--- /dev/null
+++ b/lib/service/users/chpc.rs
@@ -0,0 +1,17 @@
+use crate::{
+    AppService,
+    error::AppError,
+    user::chpc::{ContributionHeatmapQuery, ContributionHeatmapResponse},
+};
+
+impl AppService {
+    pub async fn users_chpc_by_username(
+        &self,
+        username: &str,
+        query: ContributionHeatmapQuery,
+    ) -> Result<ContributionHeatmapResponse, AppError> {
+        let user = self.users_find_active_user_by_username(username).await?;
+        self.user_contribution_heatmap_for_user(user.id, user.username, query)
+            .await
+    }
+}
diff --git a/lib/service/users/mod.rs b/lib/service/users/mod.rs
new file mode 100644
index 0000000..4aa6448
--- /dev/null
+++ b/lib/service/users/mod.rs
@@ -0,0 +1,4 @@
+pub mod chpc;
+pub mod public;
+pub mod relation;
+pub mod summary;
diff --git a/lib/service/users/public.rs b/lib/service/users/public.rs
new file mode 100644
index 0000000..bf50298
--- /dev/null
+++ b/lib/service/users/public.rs
@@ -0,0 +1,72 @@
+use db::sqlx;
+use model::users::{UserPrivacyModel, UserProfileModel};
+use serde::{Deserialize, Serialize};
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct PublicUserResponse {
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+    pub website_url: String,
+    pub language: String,
+    pub timezone: String,
+    pub allow_direct_messages: bool,
+    pub show_online_status: bool,
+}
+
+impl AppService {
+    pub async fn users_public_by_username(
+        &self,
+        username: &str,
+    ) -> Result<PublicUserResponse, AppError> {
+        let user = self.users_find_active_user_by_username(username).await?;
+
+        let privacy = sqlx::query_as::<_, UserPrivacyModel>(
+            "SELECT \"user\", profile_visibility, email_visibility, activity_visibility, allow_search_indexing, allow_direct_messages, show_online_status, created_at, updated_at \
+             FROM user_privacy WHERE \"user\" = $1",
+        )
+        .bind(user.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if privacy
+            .as_ref()
+            .is_some_and(|privacy| privacy.profile_visibility == "private")
+        {
+            return Err(AppError::Forbidden("profile is private".to_string()));
+        }
+
+        let profile = sqlx::query_as::<_, UserProfileModel>(
+            "SELECT \"user\", language, theme, timezone, created_at, updated_at \
+             FROM user_profile WHERE \"user\" = $1",
+        )
+        .bind(user.id)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(PublicUserResponse {
+            username: user.username,
+            display_name: user.display_name,
+            avatar_url: user.avatar_url,
+            website_url: user.website_url,
+            language: profile
+                .as_ref()
+                .map(|profile| profile.language.clone())
+                .unwrap_or_else(|| "en".to_string()),
+            timezone: profile
+                .map(|profile| profile.timezone)
+                .unwrap_or_else(|| "UTC".to_string()),
+            allow_direct_messages: privacy
+                .as_ref()
+                .map(|privacy| privacy.allow_direct_messages)
+                .unwrap_or(true),
+            show_online_status: privacy
+                .map(|privacy| privacy.show_online_status)
+                .unwrap_or(true),
+        })
+    }
+}
diff --git a/lib/service/users/relation.rs b/lib/service/users/relation.rs
new file mode 100644
index 0000000..8a5629c
--- /dev/null
+++ b/lib/service/users/relation.rs
@@ -0,0 +1,401 @@
+use std::collections::HashMap;
+
+use db::sqlx;
+use model::users::UserModel;
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, Pagination, error::AppError, non_empty, session_user};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserRelationStatus {
+    pub username: String,
+    pub avatar_url: Option<String>,
+    pub is_following: bool,
+    pub is_followed_by: bool,
+    pub is_blocked: bool,
+    pub has_blocked_me: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserRelationCard {
+    pub username: String,
+    pub display_name: Option<String>,
+    pub avatar_url: Option<String>,
+    pub is_following: bool,
+    pub is_blocked: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserRelationCounts {
+    pub followers: i64,
+    pub following: i64,
+    pub blocked: i64,
+}
+
+impl AppService {
+    pub async fn users_follow_by_username(
+        &self,
+        ctx: &Session,
+        username: &str,
+    ) -> Result<UserRelationStatus, AppError> {
+        let current_uid = session_user(ctx)?;
+        let target = self.users_relation_target(current_uid, username).await?;
+
+        if self.users_is_blocked(current_uid, target.id).await?
+            || self.users_is_blocked(target.id, current_uid).await?
+        {
+            return Err(AppError::Forbidden(
+                "cannot follow a blocked user".to_string(),
+            ));
+        }
+
+        if !self.users_is_following(current_uid, target.id).await? {
+            sqlx::query(
+                "INSERT INTO user_favorite (\"user\", target, created_at) VALUES ($1, $2, $3)",
+            )
+            .bind(current_uid)
+            .bind(target.id)
+            .bind(chrono::Utc::now())
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        self.users_relation_status_for(current_uid, target).await
+    }
+
+    pub async fn users_unfollow_by_username(
+        &self,
+        ctx: &Session,
+        username: &str,
+    ) -> Result<UserRelationStatus, AppError> {
+        let current_uid = session_user(ctx)?;
+        let target = self.users_relation_target(current_uid, username).await?;
+
+        sqlx::query(
+            "DELETE FROM user_favorite WHERE \"user\" = $1 AND target = $2",
+        )
+        .bind(current_uid)
+        .bind(target.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.users_relation_status_for(current_uid, target).await
+    }
+
+    pub async fn users_block_by_username(
+        &self,
+        ctx: &Session,
+        username: &str,
+    ) -> Result<UserRelationStatus, AppError> {
+        let current_uid = session_user(ctx)?;
+        let target = self.users_relation_target(current_uid, username).await?;
+
+        if !self.users_is_blocked(current_uid, target.id).await? {
+            sqlx::query(
+                "INSERT INTO user_blacklist (\"user\", black, created_at) VALUES ($1, $2, $3)",
+            )
+            .bind(current_uid)
+            .bind(target.id)
+            .bind(chrono::Utc::now())
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        sqlx::query(
+            "DELETE FROM user_favorite \
+             WHERE (\"user\" = $1 AND target = $2) OR (\"user\" = $2 AND target = $1)",
+        )
+        .bind(current_uid)
+        .bind(target.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.users_relation_status_for(current_uid, target).await
+    }
+
+    pub async fn users_unblock_by_username(
+        &self,
+        ctx: &Session,
+        username: &str,
+    ) -> Result<UserRelationStatus, AppError> {
+        let current_uid = session_user(ctx)?;
+        let target = self.users_relation_target(current_uid, username).await?;
+
+        sqlx::query(
+            "DELETE FROM user_blacklist WHERE \"user\" = $1 AND black = $2",
+        )
+        .bind(current_uid)
+        .bind(target.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.users_relation_status_for(current_uid, target).await
+    }
+
+    pub async fn users_relation_status_by_username(
+        &self,
+        ctx: &Session,
+        username: &str,
+    ) -> Result<UserRelationStatus, AppError> {
+        let current_uid = session_user(ctx)?;
+        let target = self.users_relation_target(current_uid, username).await?;
+        self.users_relation_status_for(current_uid, target).await
+    }
+
+    pub async fn users_followers_by_username(
+        &self,
+        ctx: Option<&Session>,
+        username: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<UserRelationCard>, AppError> {
+        let target = self.users_find_active_user_by_username(username).await?;
+        let current_uid = ctx.and_then(Session::user);
+        let users = sqlx::query_as::<_, UserModel>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+                    u.last_sign_in_at, u.created_at, u.updated_at \
+             FROM user_favorite f \
+             INNER JOIN \"user\" u ON u.id = f.\"user\" \
+             WHERE f.target = $1 AND u.allow_use = true \
+             ORDER BY f.created_at DESC \
+             LIMIT $2 OFFSET $3",
+        )
+        .bind(target.id)
+        .bind(pagination.limit() as i64)
+        .bind(pagination.offset() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.users_relation_cards(current_uid, users).await
+    }
+
+    pub async fn users_following_by_username(
+        &self,
+        ctx: Option<&Session>,
+        username: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<UserRelationCard>, AppError> {
+        let target = self.users_find_active_user_by_username(username).await?;
+        let current_uid = ctx.and_then(Session::user);
+        let users = sqlx::query_as::<_, UserModel>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+                    u.last_sign_in_at, u.created_at, u.updated_at \
+             FROM user_favorite f \
+             INNER JOIN \"user\" u ON u.id = f.target \
+             WHERE f.\"user\" = $1 AND u.allow_use = true \
+             ORDER BY f.created_at DESC \
+             LIMIT $2 OFFSET $3",
+        )
+        .bind(target.id)
+        .bind(pagination.limit() as i64)
+        .bind(pagination.offset() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.users_relation_cards(current_uid, users).await
+    }
+
+    pub async fn users_blocked(
+        &self,
+        ctx: &Session,
+    ) -> Result<Vec<UserRelationCard>, AppError> {
+        let current_uid = session_user(ctx)?;
+        let users = sqlx::query_as::<_, UserModel>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+                    u.last_sign_in_at, u.created_at, u.updated_at \
+             FROM user_blacklist b \
+             INNER JOIN \"user\" u ON u.id = b.black \
+             WHERE b.\"user\" = $1 AND u.allow_use = true \
+             ORDER BY b.created_at DESC",
+        )
+        .bind(current_uid)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        self.users_relation_cards(Some(current_uid), users).await
+    }
+
+    pub async fn users_relation_counts_by_username(
+        &self,
+        username: &str,
+    ) -> Result<UserRelationCounts, AppError> {
+        let target = self.users_find_active_user_by_username(username).await?;
+        let followers = sqlx::query_scalar::<_, i64>(
+            "SELECT COUNT(*) FROM user_favorite f \
+             INNER JOIN \"user\" u ON u.id = f.\"user\" \
+             WHERE f.target = $1 AND u.allow_use = true",
+        )
+        .bind(target.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let following = sqlx::query_scalar::<_, i64>(
+            "SELECT COUNT(*) FROM user_favorite f \
+             INNER JOIN \"user\" u ON u.id = f.target \
+             WHERE f.\"user\" = $1 AND u.allow_use = true",
+        )
+        .bind(target.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let blocked = sqlx::query_scalar::<_, i64>(
+            "SELECT COUNT(*) FROM user_blacklist b \
+             INNER JOIN \"user\" u ON u.id = b.black \
+             WHERE b.\"user\" = $1 AND u.allow_use = true",
+        )
+        .bind(target.id)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(UserRelationCounts {
+            followers,
+            following,
+            blocked,
+        })
+    }
+
+    async fn users_relation_target(
+        &self,
+        current_uid: uuid::Uuid,
+        username: &str,
+    ) -> Result<UserModel, AppError> {
+        let target = self.users_find_active_user_by_username(username).await?;
+        if target.id == current_uid {
+            return Err(AppError::BadRequest(
+                "cannot operate on yourself".to_string(),
+            ));
+        }
+        Ok(target)
+    }
+
+    async fn users_relation_status_for(
+        &self,
+        current_uid: uuid::Uuid,
+        target: UserModel,
+    ) -> Result<UserRelationStatus, AppError> {
+        Ok(UserRelationStatus {
+            username: target.username,
+            avatar_url: non_empty(target.avatar_url),
+            is_following: self
+                .users_is_following(current_uid, target.id)
+                .await?,
+            is_followed_by: self
+                .users_is_following(target.id, current_uid)
+                .await?,
+            is_blocked: self.users_is_blocked(current_uid, target.id).await?,
+            has_blocked_me: self
+                .users_is_blocked(target.id, current_uid)
+                .await?,
+        })
+    }
+
+    async fn users_relation_cards(
+        &self,
+        current_uid: Option<uuid::Uuid>,
+        users: Vec<UserModel>,
+    ) -> Result<Vec<UserRelationCard>, AppError> {
+        let user_ids = users.iter().map(|user| user.id).collect::<Vec<_>>();
+        let following = match current_uid {
+            Some(current_uid) => {
+                self.users_following_set(current_uid, &user_ids).await?
+            }
+            None => HashMap::new(),
+        };
+        let blocked = match current_uid {
+            Some(current_uid) => {
+                self.users_blocked_set(current_uid, &user_ids).await?
+            }
+            None => HashMap::new(),
+        };
+
+        Ok(users
+            .into_iter()
+            .map(|user| UserRelationCard {
+                username: user.username,
+                display_name: non_empty(user.display_name),
+                avatar_url: non_empty(user.avatar_url),
+                is_following: following.contains_key(&user.id),
+                is_blocked: blocked.contains_key(&user.id),
+            })
+            .collect())
+    }
+
+    async fn users_is_following(
+        &self,
+        user_uid: uuid::Uuid,
+        target_uid: uuid::Uuid,
+    ) -> Result<bool, AppError> {
+        let exists = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM user_favorite WHERE \"user\" = $1 AND target = $2)",
+        )
+        .bind(user_uid)
+        .bind(target_uid)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(exists)
+    }
+
+    async fn users_is_blocked(
+        &self,
+        user_uid: uuid::Uuid,
+        target_uid: uuid::Uuid,
+    ) -> Result<bool, AppError> {
+        let exists = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM user_blacklist WHERE \"user\" = $1 AND black = $2)",
+        )
+        .bind(user_uid)
+        .bind(target_uid)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(exists)
+    }
+
+    async fn users_following_set(
+        &self,
+        user_uid: uuid::Uuid,
+        target_uids: &[uuid::Uuid],
+    ) -> Result<HashMap<uuid::Uuid, ()>, AppError> {
+        if target_uids.is_empty() {
+            return Ok(HashMap::new());
+        }
+        let rows = sqlx::query_as::<_, (uuid::Uuid,)>(
+            "SELECT target FROM user_favorite WHERE \"user\" = $1 AND target = ANY($2)",
+        )
+        .bind(user_uid)
+        .bind(target_uids)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(rows.into_iter().map(|(uid,)| (uid, ())).collect())
+    }
+
+    async fn users_blocked_set(
+        &self,
+        user_uid: uuid::Uuid,
+        target_uids: &[uuid::Uuid],
+    ) -> Result<HashMap<uuid::Uuid, ()>, AppError> {
+        if target_uids.is_empty() {
+            return Ok(HashMap::new());
+        }
+        let rows = sqlx::query_as::<_, (uuid::Uuid,)>(
+            "SELECT black FROM user_blacklist WHERE \"user\" = $1 AND black = ANY($2)",
+        )
+        .bind(user_uid)
+        .bind(target_uids)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(rows.into_iter().map(|(uid,)| (uid, ())).collect())
+    }
+}
diff --git a/lib/service/users/summary.rs b/lib/service/users/summary.rs
new file mode 100644
index 0000000..98a4895
--- /dev/null
+++ b/lib/service/users/summary.rs
@@ -0,0 +1,70 @@
+use db::sqlx;
+use model::users::UserModel;
+use serde::{Deserialize, Serialize};
+
+use crate::{AppService, error::AppError};
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct UserSummaryResponse {
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+    pub website_url: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl AppService {
+    pub async fn users_summary_by_username(
+        &self,
+        username: &str,
+    ) -> Result<UserSummaryResponse, AppError> {
+        let user = self.users_find_active_user_by_username(username).await?;
+        Ok(user.into())
+    }
+
+    /// Get a user's avatar URL by username.
+    pub async fn users_get_avatar_url(
+        &self,
+        username: &str,
+    ) -> Result<String, AppError> {
+        let user = self.users_find_active_user_by_username(username).await?;
+        if user.avatar_url.is_empty() {
+            return Err(AppError::NotFound("avatar not found".to_string()));
+        }
+        Ok(user.avatar_url)
+    }
+
+    pub(crate) async fn users_find_active_user_by_username(
+        &self,
+        username: &str,
+    ) -> Result<UserModel, AppError> {
+        let user = sqlx::query_as::<_, UserModel>(
+            "SELECT id, username, display_name, avatar_url, website_url, allow_use, can_search, \
+                    last_sign_in_at, created_at, updated_at \
+             FROM \"user\" WHERE username = $1",
+        )
+        .bind(username)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::UserNotFound)?;
+
+        if !user.allow_use {
+            return Err(AppError::UserNotFound);
+        }
+        Ok(user)
+    }
+}
+
+impl From<UserModel> for UserSummaryResponse {
+    fn from(value: UserModel) -> Self {
+        Self {
+            username: value.username,
+            display_name: value.display_name,
+            avatar_url: value.avatar_url,
+            website_url: value.website_url,
+            created_at: value.created_at,
+        }
+    }
+}
diff --git a/lib/service/workspace/group.rs b/lib/service/workspace/group.rs
new file mode 100644
index 0000000..a3f35f4
--- /dev/null
+++ b/lib/service/workspace/group.rs
@@ -0,0 +1,227 @@
+use db::sqlx;
+use model::workspace::WkGroupModel;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{
+    WorkspaceGroupMemberRow, WorkspaceGroupResponse, WorkspaceMemberResponse,
+    group_response,
+};
+use crate::{AppService, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateWorkspaceGroup {
+    pub name: String,
+    pub avatar_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateWorkspaceGroup {
+    pub name: Option<String>,
+    pub avatar_url: Option<Option<String>>,
+}
+
+impl AppService {
+    pub async fn workspace_groups(
+        &self,
+        ctx: &Session,
+        name: &str,
+    ) -> Result<Vec<WorkspaceGroupResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let rows = sqlx::query_as::<_, WkGroupModel>(
+            "SELECT id, name, wk, created_at, avatar_url, is_deleted FROM wk_group \
+             WHERE wk = $1 ORDER BY created_at DESC",
+        )
+        .bind(wk.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows.into_iter().map(group_response).collect())
+    }
+
+    pub async fn workspace_create_group(
+        &self,
+        ctx: &Session,
+        name: &str,
+        params: CreateWorkspaceGroup,
+    ) -> Result<WorkspaceGroupResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        use super::types::normalize_name;
+        let group_name = normalize_name(&params.name)?;
+
+        let row = sqlx::query_as::<_, WkGroupModel>(
+            "INSERT INTO wk_group (id, name, wk, created_at, avatar_url, is_deleted) \
+             VALUES ($1, $2, $3, $4, $5, false) \
+             RETURNING id, name, wk, created_at, avatar_url, is_deleted",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(group_name)
+        .bind(wk.id)
+        .bind(chrono::Utc::now())
+        .bind(params.avatar_url)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(group_response(row))
+    }
+
+    pub async fn workspace_update_group(
+        &self,
+        ctx: &Session,
+        name: &str,
+        group_name: &str,
+        params: UpdateWorkspaceGroup,
+    ) -> Result<WorkspaceGroupResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let group = self.workspace_group_by_name(wk.id, group_name).await?;
+
+        use super::types::normalize_name;
+        let group_name = match params.name {
+            Some(name) => normalize_name(&name)?,
+            None => group.name,
+        };
+        let avatar_url = params.avatar_url.unwrap_or(group.avatar_url);
+
+        let row = sqlx::query_as::<_, WkGroupModel>(
+            "UPDATE wk_group SET name = $1, avatar_url = $2 WHERE id = $3 AND wk = $4 \
+             RETURNING id, name, wk, created_at, avatar_url, is_deleted",
+        )
+        .bind(group_name)
+        .bind(avatar_url)
+        .bind(group.id)
+        .bind(wk.id)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(group_response(row))
+    }
+
+    pub async fn workspace_delete_group(
+        &self,
+        ctx: &Session,
+        name: &str,
+        group_name: &str,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let group = self.workspace_group_by_name(wk.id, group_name).await?;
+        sqlx::query(
+            "UPDATE wk_group SET is_deleted = true WHERE id = $1 AND wk = $2",
+        )
+        .bind(group.id)
+        .bind(wk.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+
+    pub async fn workspace_add_group_member(
+        &self,
+        ctx: &Session,
+        name: &str,
+        group_name: &str,
+        username: &str,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let group = self.workspace_group_by_name(wk.id, group_name).await?;
+        let target = self.users_find_active_user_by_username(username).await?;
+        self.workspace_require_member(wk.id, target.id).await?;
+
+        sqlx::query(
+            "INSERT INTO wk_gp_member (\"user\", gp, join_at, leave_at) VALUES ($1, $2, $3, NULL) \
+             ON CONFLICT (\"user\", gp) DO UPDATE SET leave_at = NULL",
+        )
+        .bind(target.id)
+        .bind(group.id)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+
+    pub async fn workspace_remove_group_member(
+        &self,
+        ctx: &Session,
+        name: &str,
+        group_name: &str,
+        username: &str,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let group = self.workspace_group_by_name(wk.id, group_name).await?;
+        let target = self.users_find_active_user_by_username(username).await?;
+
+        sqlx::query("UPDATE wk_gp_member SET leave_at = $1 WHERE \"user\" = $2 AND gp = $3")
+            .bind(chrono::Utc::now())
+            .bind(target.id)
+            .bind(group.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+
+    pub async fn workspace_group_members(
+        &self,
+        ctx: &Session,
+        name: &str,
+        group_name: &str,
+    ) -> Result<Vec<WorkspaceMemberResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+        let group = self.workspace_group_by_name(wk.id, group_name).await?;
+
+        let rows = sqlx::query_as::<_, WorkspaceGroupMemberRow>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+                    u.last_sign_in_at, u.created_at, u.updated_at, gm.join_at \
+             FROM wk_gp_member gm \
+             INNER JOIN \"user\" u ON u.id = gm.\"user\" \
+             WHERE gm.gp = $1 AND gm.leave_at IS NULL \
+             ORDER BY gm.join_at ASC",
+        )
+        .bind(group.id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(WorkspaceMemberResponse::from)
+            .collect())
+    }
+
+    pub(crate) async fn workspace_group_by_name(
+        &self,
+        wk_id: uuid::Uuid,
+        group_name: &str,
+    ) -> Result<WkGroupModel, AppError> {
+        sqlx::query_as::<_, WkGroupModel>(
+            "SELECT id, name, wk, created_at, avatar_url, is_deleted \
+             FROM wk_group WHERE wk = $1 AND name = $2 AND is_deleted = false",
+        )
+        .bind(wk_id)
+        .bind(group_name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("workspace group not found".to_string()))
+    }
+}
diff --git a/lib/service/workspace/join.rs b/lib/service/workspace/join.rs
new file mode 100644
index 0000000..46898b2
--- /dev/null
+++ b/lib/service/workspace/join.rs
@@ -0,0 +1,609 @@
+use db::sqlx;
+use model::workspace::{
+    WkApplyJoinModel, WkJoinApprovalModel, WkJoinStrategyModel, WorkspaceModel,
+};
+use serde::{Deserialize, Serialize};
+use session::Session;
+
+use crate::{AppService, error::AppError, session_user};
+
+const JOIN_STATUS_PENDING: &str = "pending";
+const JOIN_STATUS_APPROVED: &str = "approved";
+const JOIN_STATUS_REJECTED: &str = "rejected";
+const JOIN_STATUS_CANCELLED: &str = "cancelled";
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WorkspaceJoinStrategyResponse {
+    pub workspace_name: String,
+    pub workspace_avatar_url: String,
+    pub require_approval: bool,
+    pub require_question: bool,
+    pub question: Option<String>,
+    pub has_answer: bool,
+    pub enabled: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateWorkspaceJoinStrategy {
+    pub require_approval: Option<bool>,
+    pub require_question: Option<bool>,
+    pub question: Option<Option<String>>,
+    pub answer: Option<Option<String>>,
+    pub enabled: Option<bool>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WorkspaceJoinApplyResponse {
+    pub workspace_name: String,
+    pub workspace_avatar_url: String,
+    pub username: String,
+    pub avatar_url: Option<String>,
+    pub status: String,
+    pub question: Option<String>,
+    pub answer: Option<String>,
+    pub message: Option<String>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    #[schema(value_type = String)]
+    pub updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateWorkspaceJoinApply {
+    pub answer: Option<String>,
+    pub message: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema, utoipa::IntoParams)]
+pub struct ListWorkspaceJoinApply {
+    pub status: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WorkspaceJoinApprovalResponse {
+    pub workspace_name: String,
+    pub workspace_avatar_url: String,
+    pub username: String,
+    pub avatar_url: Option<String>,
+    pub approver_username: String,
+    pub approver_avatar_url: Option<String>,
+    pub approved: bool,
+    pub reason: Option<String>,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct ApproveWorkspaceJoinApply {
+    pub approved: bool,
+    pub reason: Option<String>,
+}
+
+impl AppService {
+    pub async fn workspace_join_strategy(
+        &self,
+        name: &str,
+    ) -> Result<WorkspaceJoinStrategyResponse, AppError> {
+        let wk = self.workspace_resolve(name).await?;
+        let strategy = self.workspace_join_strategy_by_wk(wk.id).await?;
+        Ok(strategy_response(strategy, &wk))
+    }
+
+    pub async fn workspace_update_join_strategy(
+        &self,
+        ctx: &Session,
+        name: &str,
+        params: UpdateWorkspaceJoinStrategy,
+    ) -> Result<WorkspaceJoinStrategyResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let existing = self.workspace_join_strategy_by_wk(wk.id).await?;
+        let require_approval =
+            params.require_approval.unwrap_or(existing.require_approval);
+        let mut require_question =
+            params.require_question.unwrap_or(existing.require_question);
+        let question = params.question.unwrap_or(existing.question);
+        let answer = params.answer.unwrap_or(existing.answer);
+        let enabled = params.enabled.unwrap_or(existing.enabled);
+
+        if require_question
+            && question
+                .as_ref()
+                .is_none_or(|question| question.trim().is_empty())
+        {
+            return Err(AppError::BadRequest(
+                "join question is required when require_question is true"
+                    .to_string(),
+            ));
+        }
+        if question.is_none() {
+            require_question = false;
+        }
+
+        let now = chrono::Utc::now();
+        let saved = if self.workspace_join_strategy_exists(wk.id).await? {
+            sqlx::query_as::<_, WkJoinStrategyModel>(
+                "UPDATE wk_join_strategy SET require_approval = $1, require_question = $2, \
+                    question = $3, answer = $4, enabled = $5, updated_at = $6 \
+                 WHERE wk = $7 \
+                 RETURNING wk, require_approval, require_question, question, answer, enabled, created_at, updated_at",
+            )
+            .bind(require_approval)
+            .bind(require_question)
+            .bind(clean_optional(question))
+            .bind(clean_optional(answer))
+            .bind(enabled)
+            .bind(now)
+            .bind(wk.id)
+            .fetch_one(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        } else {
+            sqlx::query_as::<_, WkJoinStrategyModel>(
+                "INSERT INTO wk_join_strategy \
+                    (wk, require_approval, require_question, question, answer, enabled, created_at, updated_at) \
+                 VALUES ($1, $2, $3, $4, $5, $6, $7, $7) \
+                 RETURNING wk, require_approval, require_question, question, answer, enabled, created_at, updated_at",
+            )
+            .bind(wk.id)
+            .bind(require_approval)
+            .bind(require_question)
+            .bind(clean_optional(question))
+            .bind(clean_optional(answer))
+            .bind(enabled)
+            .bind(now)
+            .fetch_one(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        };
+
+        Ok(strategy_response(saved, &wk))
+    }
+
+    pub async fn workspace_apply_join(
+        &self,
+        ctx: &Session,
+        name: &str,
+        params: CreateWorkspaceJoinApply,
+    ) -> Result<WorkspaceJoinApplyResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        if self.workspace_member(wk.id, user_uid).await.is_ok() {
+            return Err(AppError::Conflict(
+                "user is already a workspace member".to_string(),
+            ));
+        }
+        if self
+            .workspace_has_pending_join_apply(wk.id, user_uid)
+            .await?
+        {
+            return Err(AppError::Conflict(
+                "join application is already pending".to_string(),
+            ));
+        }
+
+        let strategy = self.workspace_join_strategy_by_wk(wk.id).await?;
+        let answer = clean_optional(params.answer);
+        if strategy.enabled && strategy.require_question {
+            let expected = strategy
+                .answer
+                .as_ref()
+                .map(|answer| answer.trim())
+                .unwrap_or_default();
+            let actual = answer
+                .as_ref()
+                .map(|answer| answer.trim())
+                .unwrap_or_default();
+            if actual.is_empty() {
+                return Err(AppError::BadRequest(
+                    "join answer is required".to_string(),
+                ));
+            }
+            if !expected.is_empty() && actual != expected {
+                return Err(AppError::PermissionDenied);
+            }
+        }
+
+        let status = if strategy.enabled && strategy.require_approval {
+            JOIN_STATUS_PENDING
+        } else {
+            JOIN_STATUS_APPROVED
+        };
+
+        let now = chrono::Utc::now();
+        let apply = sqlx::query_as::<_, WkApplyJoinModel>(
+            "INSERT INTO wk_apply_join \
+                (id, wk, \"user\", status, question, answer, message, created_at, updated_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $8) \
+             RETURNING id, wk, \"user\", status, question, answer, message, created_at, updated_at",
+        )
+        .bind(uuid::Uuid::now_v7())
+        .bind(wk.id)
+        .bind(user_uid)
+        .bind(status)
+        .bind(strategy.question.clone())
+        .bind(answer)
+        .bind(clean_optional(params.message))
+        .bind(now)
+        .fetch_one(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if status == JOIN_STATUS_APPROVED {
+            self.workspace_join_add_member(wk.id, user_uid).await?;
+        }
+
+        let current_user = self.auth_find_user_by_uid(user_uid).await?;
+        Ok(apply_response(
+            apply,
+            &wk,
+            current_user.username,
+            clean_optional(Some(current_user.avatar_url)),
+        ))
+    }
+
+    pub async fn workspace_my_join_applies(
+        &self,
+        ctx: &Session,
+    ) -> Result<Vec<WorkspaceJoinApplyResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let rows = sqlx::query_as::<_, WorkspaceJoinApplyRow>(
+            "SELECT a.id, a.wk, w.name AS workspace_name, w.avatar_url AS workspace_avatar_url, \
+                    a.\"user\", u.username, u.avatar_url, a.status, a.question, a.answer, a.message, a.created_at, a.updated_at \
+             FROM wk_apply_join a \
+             INNER JOIN workspace w ON w.id = a.wk \
+             INNER JOIN \"user\" u ON u.id = a.\"user\" \
+             WHERE a.\"user\" = $1 ORDER BY a.created_at DESC",
+        )
+        .bind(user_uid)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(WorkspaceJoinApplyResponse::from)
+            .collect())
+    }
+
+    pub async fn workspace_cancel_join_apply(
+        &self,
+        ctx: &Session,
+        name: &str,
+    ) -> Result<WorkspaceJoinApplyResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        let user = self.auth_find_user_by_uid(user_uid).await?;
+        let apply = sqlx::query_as::<_, WkApplyJoinModel>(
+            "UPDATE wk_apply_join SET status = $1, updated_at = $2 \
+             WHERE wk = $3 AND \"user\" = $4 AND status = $5 \
+             RETURNING id, wk, \"user\", status, question, answer, message, created_at, updated_at",
+        )
+        .bind(JOIN_STATUS_CANCELLED)
+        .bind(chrono::Utc::now())
+        .bind(wk.id)
+        .bind(user_uid)
+        .bind(JOIN_STATUS_PENDING)
+        .fetch_optional(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("join application not found".to_string()))?;
+
+        Ok(apply_response(
+            apply,
+            &wk,
+            user.username,
+            clean_optional(Some(user.avatar_url)),
+        ))
+    }
+
+    pub async fn workspace_join_applies(
+        &self,
+        ctx: &Session,
+        name: &str,
+        query: ListWorkspaceJoinApply,
+    ) -> Result<Vec<WorkspaceJoinApplyResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let status = query
+            .status
+            .unwrap_or_else(|| JOIN_STATUS_PENDING.to_string());
+
+        let rows = sqlx::query_as::<_, WorkspaceJoinApplyRow>(
+            "SELECT a.id, a.wk, w.name AS workspace_name, w.avatar_url AS workspace_avatar_url, \
+                    a.\"user\", u.username, u.avatar_url, a.status, a.question, a.answer, a.message, a.created_at, a.updated_at \
+             FROM wk_apply_join a \
+             INNER JOIN workspace w ON w.id = a.wk \
+             INNER JOIN \"user\" u ON u.id = a.\"user\" \
+             WHERE a.wk = $1 AND a.status = $2 \
+             ORDER BY a.created_at ASC",
+        )
+        .bind(wk.id)
+        .bind(status)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(WorkspaceJoinApplyResponse::from)
+            .collect())
+    }
+
+    pub async fn workspace_approve_join_apply(
+        &self,
+        ctx: &Session,
+        name: &str,
+        username: &str,
+        params: ApproveWorkspaceJoinApply,
+    ) -> Result<WorkspaceJoinApprovalResponse, AppError> {
+        let approver = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, approver).await?;
+        let applicant =
+            self.users_find_active_user_by_username(username).await?;
+        let approver_user = self.auth_find_user_by_uid(approver).await?;
+        let apply = self
+            .workspace_pending_join_apply_by_user(wk.id, applicant.id)
+            .await?;
+        if apply.status != JOIN_STATUS_PENDING {
+            return Err(AppError::Conflict(
+                "join application has already been processed".to_string(),
+            ));
+        }
+
+        let now = chrono::Utc::now();
+        let approval_id = uuid::Uuid::now_v7();
+        let next_status = if params.approved {
+            JOIN_STATUS_APPROVED
+        } else {
+            JOIN_STATUS_REJECTED
+        };
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+        let approval = sqlx::query_as::<_, WkJoinApprovalModel>(
+            "INSERT INTO wk_join_approval \
+                (id, apply, wk, \"user\", approver, approved, reason, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8) \
+             RETURNING id, apply, wk, \"user\", approver, approved, reason, created_at",
+        )
+        .bind(approval_id)
+        .bind(apply.id)
+        .bind(wk.id)
+        .bind(apply.user)
+        .bind(approver)
+        .bind(params.approved)
+        .bind(clean_optional(params.reason))
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query("UPDATE wk_apply_join SET status = $1, updated_at = $2 WHERE id = $3")
+            .bind(next_status)
+            .bind(now)
+            .bind(apply.id)
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if params.approved {
+            sqlx::query(
+                "INSERT INTO wk_member (wk, \"user\", owner, admin, join_at, leave_at) \
+                 VALUES ($1, $2, false, false, $3, NULL) \
+                 ON CONFLICT (wk, \"user\") DO UPDATE SET leave_at = NULL",
+            )
+            .bind(wk.id)
+            .bind(apply.user)
+            .bind(now)
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        }
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        Ok(approval_response(
+            approval,
+            &wk,
+            applicant.username,
+            clean_optional(Some(applicant.avatar_url)),
+            approver_user.username,
+            clean_optional(Some(approver_user.avatar_url)),
+        ))
+    }
+
+    async fn workspace_join_strategy_by_wk(
+        &self,
+        wk: uuid::Uuid,
+    ) -> Result<WkJoinStrategyModel, AppError> {
+        let strategy = sqlx::query_as::<_, WkJoinStrategyModel>(
+            "SELECT wk, require_approval, require_question, question, answer, enabled, created_at, updated_at \
+             FROM wk_join_strategy WHERE wk = $1",
+        )
+        .bind(wk)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let now = chrono::Utc::now();
+        Ok(strategy.unwrap_or(WkJoinStrategyModel {
+            wk,
+            require_approval: false,
+            require_question: false,
+            question: None,
+            answer: None,
+            enabled: false,
+            created_at: now,
+            updated_at: now,
+        }))
+    }
+
+    async fn workspace_join_strategy_exists(
+        &self,
+        wk: uuid::Uuid,
+    ) -> Result<bool, AppError> {
+        sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM wk_join_strategy WHERE wk = $1)",
+        )
+        .bind(wk)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))
+    }
+
+    async fn workspace_has_pending_join_apply(
+        &self,
+        wk: uuid::Uuid,
+        user: uuid::Uuid,
+    ) -> Result<bool, AppError> {
+        sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM wk_apply_join WHERE wk = $1 AND \"user\" = $2 AND status = $3)",
+        )
+        .bind(wk)
+        .bind(user)
+        .bind(JOIN_STATUS_PENDING)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))
+    }
+
+    async fn workspace_pending_join_apply_by_user(
+        &self,
+        wk: uuid::Uuid,
+        user: uuid::Uuid,
+    ) -> Result<WkApplyJoinModel, AppError> {
+        sqlx::query_as::<_, WkApplyJoinModel>(
+            "SELECT id, wk, \"user\", status, question, answer, message, created_at, updated_at \
+             FROM wk_apply_join WHERE wk = $1 AND \"user\" = $2 AND status = $3",
+        )
+        .bind(wk)
+        .bind(user)
+        .bind(JOIN_STATUS_PENDING)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::NotFound("join application not found".to_string()))
+    }
+
+    async fn workspace_join_add_member(
+        &self,
+        wk: uuid::Uuid,
+        user: uuid::Uuid,
+    ) -> Result<(), AppError> {
+        sqlx::query(
+            "INSERT INTO wk_member (wk, \"user\", owner, admin, join_at, leave_at) \
+             VALUES ($1, $2, false, false, $3, NULL) \
+             ON CONFLICT (wk, \"user\") DO UPDATE SET leave_at = NULL",
+        )
+        .bind(wk)
+        .bind(user)
+        .bind(chrono::Utc::now())
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+}
+
+#[derive(db::sqlx::FromRow)]
+struct WorkspaceJoinApplyRow {
+    workspace_name: String,
+    workspace_avatar_url: String,
+    username: String,
+    avatar_url: String,
+    status: String,
+    question: Option<String>,
+    answer: Option<String>,
+    message: Option<String>,
+    created_at: chrono::DateTime<chrono::Utc>,
+    updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+fn strategy_response(
+    value: WkJoinStrategyModel,
+    wk: &WorkspaceModel,
+) -> WorkspaceJoinStrategyResponse {
+    WorkspaceJoinStrategyResponse {
+        workspace_name: wk.name.clone(),
+        workspace_avatar_url: wk.avatar_url.clone(),
+        require_approval: value.require_approval,
+        require_question: value.require_question,
+        question: value.question,
+        has_answer: value.answer.is_some(),
+        enabled: value.enabled,
+        created_at: value.created_at,
+        updated_at: value.updated_at,
+    }
+}
+
+fn apply_response(
+    value: WkApplyJoinModel,
+    wk: &WorkspaceModel,
+    username: String,
+    avatar_url: Option<String>,
+) -> WorkspaceJoinApplyResponse {
+    WorkspaceJoinApplyResponse {
+        workspace_name: wk.name.clone(),
+        workspace_avatar_url: wk.avatar_url.clone(),
+        username,
+        avatar_url,
+        status: value.status,
+        question: value.question,
+        answer: value.answer,
+        message: value.message,
+        created_at: value.created_at,
+        updated_at: value.updated_at,
+    }
+}
+
+fn approval_response(
+    value: WkJoinApprovalModel,
+    wk: &WorkspaceModel,
+    username: String,
+    avatar_url: Option<String>,
+    approver_username: String,
+    approver_avatar_url: Option<String>,
+) -> WorkspaceJoinApprovalResponse {
+    WorkspaceJoinApprovalResponse {
+        workspace_name: wk.name.clone(),
+        workspace_avatar_url: wk.avatar_url.clone(),
+        username,
+        avatar_url,
+        approver_username,
+        approver_avatar_url,
+        approved: value.approved,
+        reason: value.reason,
+        created_at: value.created_at,
+    }
+}
+
+fn clean_optional(value: Option<String>) -> Option<String> {
+    value.and_then(|value| {
+        let value = value.trim().to_string();
+        if value.is_empty() { None } else { Some(value) }
+    })
+}
+
+impl From<WorkspaceJoinApplyRow> for WorkspaceJoinApplyResponse {
+    fn from(value: WorkspaceJoinApplyRow) -> Self {
+        Self {
+            workspace_name: value.workspace_name,
+            workspace_avatar_url: value.workspace_avatar_url,
+            username: value.username,
+            avatar_url: clean_optional(Some(value.avatar_url)),
+            status: value.status,
+            question: value.question,
+            answer: value.answer,
+            message: value.message,
+            created_at: value.created_at,
+            updated_at: value.updated_at,
+        }
+    }
+}
diff --git a/lib/service/workspace/member.rs b/lib/service/workspace/member.rs
new file mode 100644
index 0000000..2bc8a8f
--- /dev/null
+++ b/lib/service/workspace/member.rs
@@ -0,0 +1,155 @@
+use db::sqlx;
+use serde::Deserialize;
+use session::Session;
+
+use super::types::{
+    WorkspaceMemberResponse, WorkspaceMemberRow, member_response,
+};
+use crate::{AppService, Pagination, error::AppError, session_user};
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct AddWorkspaceMember {
+    pub username: String,
+    pub admin: Option<bool>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateWorkspaceMember {
+    pub admin: bool,
+}
+
+impl AppService {
+    pub async fn workspace_members(
+        &self,
+        ctx: &Session,
+        name: &str,
+        pagination: Pagination,
+    ) -> Result<Vec<WorkspaceMemberResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_member(wk.id, user_uid).await?;
+
+        let rows = sqlx::query_as::<_, WorkspaceMemberRow>(
+            "SELECT u.id, u.username, u.display_name, u.avatar_url, u.website_url, u.allow_use, u.can_search, \
+                    u.last_sign_in_at, u.created_at, u.updated_at, m.owner, m.admin, m.join_at \
+             FROM wk_member m \
+             INNER JOIN \"user\" u ON u.id = m.\"user\" \
+             WHERE m.wk = $1 AND m.leave_at IS NULL \
+             ORDER BY m.owner DESC, m.admin DESC, m.join_at ASC \
+             LIMIT $2 OFFSET $3",
+        )
+        .bind(wk.id)
+        .bind(pagination.limit() as i64)
+        .bind(pagination.offset() as i64)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(WorkspaceMemberResponse::from)
+            .collect())
+    }
+
+    pub async fn workspace_add_member(
+        &self,
+        ctx: &Session,
+        name: &str,
+        params: AddWorkspaceMember,
+    ) -> Result<WorkspaceMemberResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+        let target = self
+            .users_find_active_user_by_username(&params.username)
+            .await?;
+
+        let now = chrono::Utc::now();
+        sqlx::query(
+            "INSERT INTO wk_member (wk, \"user\", owner, admin, join_at, leave_at) \
+             VALUES ($1, $2, false, $3, $4, NULL) \
+             ON CONFLICT (wk, \"user\") DO UPDATE SET admin = EXCLUDED.admin, leave_at = NULL",
+        )
+        .bind(wk.id)
+        .bind(target.id)
+        .bind(params.admin.unwrap_or(false))
+        .bind(now)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let member = self.workspace_member(wk.id, target.id).await?;
+        Ok(member_response(
+            target,
+            member.owner,
+            member.admin,
+            member.join_at,
+        ))
+    }
+
+    pub async fn workspace_update_member(
+        &self,
+        ctx: &Session,
+        name: &str,
+        username: &str,
+        params: UpdateWorkspaceMember,
+    ) -> Result<WorkspaceMemberResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_owner(wk.id, user_uid).await?;
+        let target = self.users_find_active_user_by_username(username).await?;
+        let member = self.workspace_member(wk.id, target.id).await?;
+        if member.owner {
+            return Err(AppError::BadRequest(
+                "cannot update workspace owner role".to_string(),
+            ));
+        }
+
+        sqlx::query(
+            "UPDATE wk_member SET admin = $1 WHERE wk = $2 AND \"user\" = $3 AND leave_at IS NULL",
+        )
+        .bind(params.admin)
+        .bind(wk.id)
+        .bind(target.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        let member = self.workspace_member(wk.id, target.id).await?;
+        Ok(member_response(
+            target,
+            member.owner,
+            member.admin,
+            member.join_at,
+        ))
+    }
+
+    pub async fn workspace_remove_member(
+        &self,
+        ctx: &Session,
+        name: &str,
+        username: &str,
+    ) -> Result<(), AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        let target = self.users_find_active_user_by_username(username).await?;
+        let target_member = self.workspace_member(wk.id, target.id).await?;
+        if target_member.owner {
+            return Err(AppError::BadRequest(
+                "cannot remove workspace owner".to_string(),
+            ));
+        }
+        if user_uid != target.id {
+            self.workspace_require_admin(wk.id, user_uid).await?;
+        }
+
+        sqlx::query("UPDATE wk_member SET leave_at = $1 WHERE wk = $2 AND \"user\" = $3")
+            .bind(chrono::Utc::now())
+            .bind(wk.id)
+            .bind(target.id)
+            .execute(self.db.writer())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(())
+    }
+}
diff --git a/lib/service/workspace/mod.rs b/lib/service/workspace/mod.rs
new file mode 100644
index 0000000..bf0bfee
--- /dev/null
+++ b/lib/service/workspace/mod.rs
@@ -0,0 +1,5 @@
+pub mod group;
+pub mod join;
+pub mod member;
+pub mod types;
+pub mod workspace;
diff --git a/lib/service/workspace/types.rs b/lib/service/workspace/types.rs
new file mode 100644
index 0000000..22492e7
--- /dev/null
+++ b/lib/service/workspace/types.rs
@@ -0,0 +1,167 @@
+use model::{
+    users::UserModel,
+    workspace::{WkGroupModel, WorkspaceModel},
+};
+use serde::{Deserialize, Serialize};
+
+use crate::{error::AppError, non_empty};
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WorkspaceResponse {
+    pub name: String,
+    pub description: String,
+    pub avatar_url: String,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    pub owner: bool,
+    pub admin: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WorkspaceMemberResponse {
+    pub username: String,
+    pub display_name: Option<String>,
+    pub avatar_url: Option<String>,
+    pub owner: bool,
+    pub admin: bool,
+    #[schema(value_type = String)]
+    pub join_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
+pub struct WorkspaceGroupResponse {
+    pub name: String,
+    pub avatar_url: Option<String>,
+    pub is_deleted: bool,
+    #[schema(value_type = String)]
+    pub created_at: chrono::DateTime<chrono::Utc>,
+}
+
+pub(crate) fn normalize_name(name: &str) -> Result<String, AppError> {
+    let name = name.trim();
+    if name.is_empty() {
+        return Err(AppError::BadRequest(
+            "workspace name is required".to_string(),
+        ));
+    }
+    if name.len() > 64 {
+        return Err(AppError::BadRequest(
+            "workspace name is too long".to_string(),
+        ));
+    }
+    if !name
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
+    {
+        return Err(AppError::BadRequest(
+            "workspace name can only contain letters, numbers, '-' and '_'"
+                .to_string(),
+        ));
+    }
+    Ok(name.to_string())
+}
+
+pub(crate) fn workspace_response(
+    wk: WorkspaceModel,
+    owner: bool,
+    admin: bool,
+) -> WorkspaceResponse {
+    WorkspaceResponse {
+        name: wk.name,
+        description: wk.description,
+        avatar_url: wk.avatar_url,
+        created_at: wk.created_at,
+        owner,
+        admin,
+    }
+}
+
+pub(crate) fn member_response(
+    user: UserModel,
+    owner: bool,
+    admin: bool,
+    join_at: chrono::DateTime<chrono::Utc>,
+) -> WorkspaceMemberResponse {
+    WorkspaceMemberResponse {
+        username: user.username,
+        display_name: non_empty(user.display_name),
+        avatar_url: non_empty(user.avatar_url),
+        owner,
+        admin,
+        join_at,
+    }
+}
+
+pub(crate) fn group_response(group: WkGroupModel) -> WorkspaceGroupResponse {
+    WorkspaceGroupResponse {
+        name: group.name,
+        avatar_url: group.avatar_url,
+        is_deleted: group.is_deleted,
+        created_at: group.created_at,
+    }
+}
+impl From<WorkspaceListRow> for WorkspaceModel {
+    fn from(value: WorkspaceListRow) -> Self {
+        Self {
+            id: value.id,
+            name: value.name,
+            description: value.description,
+            avatar_url: value.avatar_url,
+            created_at: value.created_at,
+        }
+    }
+}
+
+#[derive(db::sqlx::FromRow)]
+pub(crate) struct WorkspaceListRow {
+    id: uuid::Uuid,
+    pub name: String,
+    pub description: String,
+    pub avatar_url: String,
+    pub created_at: chrono::DateTime<chrono::Utc>,
+    pub owner: bool,
+    pub admin: bool,
+}
+
+impl From<WorkspaceMemberRow> for WorkspaceMemberResponse {
+    fn from(value: WorkspaceMemberRow) -> Self {
+        Self {
+            username: value.username,
+            display_name: non_empty(value.display_name),
+            avatar_url: non_empty(value.avatar_url),
+            owner: value.owner,
+            admin: value.admin,
+            join_at: value.join_at,
+        }
+    }
+}
+
+#[derive(db::sqlx::FromRow)]
+pub(crate) struct WorkspaceMemberRow {
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+    pub owner: bool,
+    pub admin: bool,
+    pub join_at: chrono::DateTime<chrono::Utc>,
+}
+
+impl From<WorkspaceGroupMemberRow> for WorkspaceMemberResponse {
+    fn from(value: WorkspaceGroupMemberRow) -> Self {
+        Self {
+            username: value.username,
+            display_name: non_empty(value.display_name),
+            avatar_url: non_empty(value.avatar_url),
+            owner: false,
+            admin: false,
+            join_at: value.join_at,
+        }
+    }
+}
+
+#[derive(db::sqlx::FromRow)]
+pub(crate) struct WorkspaceGroupMemberRow {
+    pub username: String,
+    pub display_name: String,
+    pub avatar_url: String,
+    pub join_at: chrono::DateTime<chrono::Utc>,
+}
diff --git a/lib/service/workspace/workspace.rs b/lib/service/workspace/workspace.rs
new file mode 100644
index 0000000..683ee57
--- /dev/null
+++ b/lib/service/workspace/workspace.rs
@@ -0,0 +1,397 @@
+use db::sqlx;
+use model::workspace::{WkMemberModel, WorkspaceModel};
+use serde::{Deserialize, Serialize};
+use session::Session;
+use storage::{ObjectStorage, PutObjectOptions};
+
+use super::types::{
+    WorkspaceListRow, WorkspaceResponse, normalize_name, workspace_response,
+};
+use crate::{AppService, error::AppError, session_user};
+
+const ALLOWED_AVATAR_TYPES: &[&str] = &[
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+];
+const MAX_AVATAR_SIZE: usize = 5 * 1024 * 1024;
+
+#[derive(Debug, Clone, Serialize, utoipa::ToSchema)]
+pub struct AvatarUploadResponse {
+    pub avatar_url: String,
+}
+
+fn extension_from_content_type(content_type: &str) -> &str {
+    match content_type {
+        "image/png" => "png",
+        "image/jpeg" => "jpg",
+        "image/webp" => "webp",
+        "image/gif" => "gif",
+        _ => "bin",
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct CreateWorkspace {
+    pub name: String,
+    pub description: Option<String>,
+    pub avatar_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, utoipa::ToSchema)]
+pub struct UpdateWorkspace {
+    pub name: Option<String>,
+    pub description: Option<String>,
+    pub avatar_url: Option<String>,
+}
+
+impl AppService {
+    pub async fn workspace_create(
+        &self,
+        ctx: &Session,
+        params: CreateWorkspace,
+    ) -> Result<WorkspaceResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let name = normalize_name(&params.name)?;
+        self.workspace_ensure_name_available(&name).await?;
+
+        let wk_id = uuid::Uuid::now_v7();
+        let now = chrono::Utc::now();
+        let description = params.description.unwrap_or_default();
+        let avatar_url = params.avatar_url.unwrap_or_default();
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+
+        let workspace = sqlx::query_as::<_, WorkspaceModel>(
+            "INSERT INTO workspace (id, name, description, avatar_url, created_at) \
+             VALUES ($1, $2, $3, $4, $5) \
+             RETURNING id, name, description, avatar_url, created_at",
+        )
+        .bind(wk_id)
+        .bind(&name)
+        .bind(&description)
+        .bind(&avatar_url)
+        .bind(now)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        sqlx::query(
+            "INSERT INTO wk_member (wk, \"user\", owner, admin, join_at, leave_at) \
+             VALUES ($1, $2, true, true, $3, NULL)",
+        )
+        .bind(wk_id)
+        .bind(user_uid)
+        .bind(now)
+        .execute(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+        Ok(workspace_response(workspace, true, true))
+    }
+
+    pub async fn workspace_my(
+        &self,
+        ctx: &Session,
+    ) -> Result<Vec<WorkspaceResponse>, AppError> {
+        let user_uid = session_user(ctx)?;
+
+        let rows = sqlx::query_as::<_, WorkspaceListRow>(
+            "SELECT w.id, w.name, w.description, w.avatar_url, w.created_at, m.owner, m.admin \
+             FROM wk_member m \
+             INNER JOIN workspace w ON w.id = m.wk \
+             WHERE m.\"user\" = $1 AND m.leave_at IS NULL \
+             ORDER BY w.created_at DESC",
+        )
+        .bind(user_uid)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(rows
+            .into_iter()
+            .map(|row| {
+                let owner = row.owner;
+                let admin = row.admin;
+                workspace_response(row.into(), owner, admin)
+            })
+            .collect())
+    }
+
+    pub async fn workspace_get(
+        &self,
+        ctx: &Session,
+        name: &str,
+    ) -> Result<WorkspaceResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        let member = self.workspace_member(wk.id, user_uid).await?;
+        Ok(workspace_response(wk, member.owner, member.admin))
+    }
+
+    pub async fn workspace_update(
+        &self,
+        ctx: &Session,
+        name: &str,
+        params: UpdateWorkspace,
+    ) -> Result<WorkspaceResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let mut wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        let next_name = match params.name {
+            Some(name) => {
+                let name = normalize_name(&name)?;
+                if name != wk.name {
+                    self.workspace_ensure_name_available(&name).await?;
+                    Some(name)
+                } else {
+                    None
+                }
+            }
+            None => None,
+        };
+        let next_avatar_url =
+            params.avatar_url.unwrap_or_else(|| wk.avatar_url.clone());
+        let next_description =
+            params.description.unwrap_or_else(|| wk.description.clone());
+
+        let mut txn = self.db.begin().await.map_err(|_| AppError::TxnError)?;
+        if let Some(next_name) = &next_name {
+            sqlx::query(
+                "INSERT INTO wk_history_name (id, wk, name, changed_by, created_at) \
+                 VALUES ($1, $2, $3, $4, $5)",
+            )
+            .bind(uuid::Uuid::now_v7())
+            .bind(wk.id)
+            .bind(&wk.name)
+            .bind(user_uid)
+            .bind(chrono::Utc::now())
+            .execute(&mut **txn.inner_mut())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+            wk.name = next_name.clone();
+        }
+
+        wk = sqlx::query_as::<_, WorkspaceModel>(
+            "UPDATE workspace SET name = $1, description = $2, avatar_url = $3 WHERE id = $4 \
+             RETURNING id, name, description, avatar_url, created_at",
+        )
+        .bind(&wk.name)
+        .bind(&next_description)
+        .bind(&next_avatar_url)
+        .bind(wk.id)
+        .fetch_one(&mut **txn.inner_mut())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        txn.commit().await.map_err(|_| AppError::TxnError)?;
+
+        let member = self.workspace_member(wk.id, user_uid).await?;
+        Ok(workspace_response(wk, member.owner, member.admin))
+    }
+
+    /// Get a workspace's avatar URL by workspace name.
+    pub async fn workspace_get_avatar_url(
+        &self,
+        name: &str,
+    ) -> Result<String, AppError> {
+        let wk = self.workspace_resolve(name).await?;
+        if wk.avatar_url.is_empty() {
+            return Err(AppError::NotFound("avatar not found".to_string()));
+        }
+        Ok(wk.avatar_url)
+    }
+
+    /// Upload a workspace avatar image, store it, and update the workspace's avatar_url.
+    pub async fn workspace_upload_avatar(
+        &self,
+        ctx: &Session,
+        name: &str,
+        bytes: Vec<u8>,
+        content_type: &str,
+    ) -> Result<AvatarUploadResponse, AppError> {
+        let user_uid = session_user(ctx)?;
+        let wk = self.workspace_resolve(name).await?;
+        self.workspace_require_admin(wk.id, user_uid).await?;
+
+        if bytes.len() > MAX_AVATAR_SIZE {
+            return Err(AppError::AvatarUploadError(
+                "file size exceeds 5 MB limit".to_string(),
+            ));
+        }
+        if !ALLOWED_AVATAR_TYPES.contains(&content_type) {
+            return Err(AppError::AvatarUploadError(format!(
+                "unsupported image type: {content_type}. Allowed: png, jpeg, webp, gif"
+            )));
+        }
+
+        let ext = extension_from_content_type(content_type);
+        let key = format!(
+            "avatars/workspaces/{wk_id}-{ts}.{ext}",
+            wk_id = wk.id,
+            ts = uuid::Uuid::now_v7()
+        );
+
+        let stored = self
+            .storage
+            .put_bytes(
+                &key,
+                bytes,
+                PutObjectOptions {
+                    content_type: Some(content_type.to_string()),
+                    ..PutObjectOptions::default()
+                },
+            )
+            .await
+            .map_err(|e| {
+                AppError::AvatarUploadError(format!("storage error: {e}"))
+            })?;
+
+        sqlx::query(
+            "UPDATE workspace SET avatar_url = $1 WHERE id = $2",
+        )
+        .bind(&stored.url)
+        .bind(wk.id)
+        .execute(self.db.writer())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        Ok(AvatarUploadResponse {
+            avatar_url: stored.url,
+        })
+    }
+
+    pub(crate) async fn workspace_resolve(
+        &self,
+        name: &str,
+    ) -> Result<WorkspaceModel, AppError> {
+        if let Some(wk) = sqlx::query_as::<_, WorkspaceModel>(
+            "SELECT id, name, description, avatar_url, created_at FROM workspace WHERE name = $1",
+        )
+        .bind(name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        {
+            return Ok(wk);
+        }
+
+        if let Some(history) = sqlx::query_as::<_, (uuid::Uuid,)>(
+            "SELECT wk FROM wk_history_name WHERE name = $1 ORDER BY created_at DESC LIMIT 1",
+        )
+        .bind(name)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        {
+            return sqlx::query_as::<_, WorkspaceModel>(
+                "SELECT id, name, description, avatar_url, created_at FROM workspace WHERE id = $1",
+            )
+            .bind(history.0)
+            .fetch_optional(self.db.reader())
+            .await
+            .map_err(|e| AppError::DatabaseError(e.to_string()))?
+            .ok_or(AppError::NotFound("workspace not found".to_string()));
+        }
+
+        Err(AppError::NotFound("workspace not found".to_string()))
+    }
+
+    pub(crate) async fn workspace_member(
+        &self,
+        wk_id: uuid::Uuid,
+        user_uid: uuid::Uuid,
+    ) -> Result<WkMemberModel, AppError> {
+        sqlx::query_as::<_, WkMemberModel>(
+            "SELECT wk, \"user\", owner, admin, join_at, leave_at \
+             FROM wk_member WHERE wk = $1 AND \"user\" = $2 AND leave_at IS NULL",
+        )
+        .bind(wk_id)
+        .bind(user_uid)
+        .fetch_optional(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?
+        .ok_or(AppError::PermissionDenied)
+    }
+
+    pub(crate) async fn workspace_require_member(
+        &self,
+        wk_id: uuid::Uuid,
+        user_uid: uuid::Uuid,
+    ) -> Result<WkMemberModel, AppError> {
+        self.workspace_member(wk_id, user_uid).await
+    }
+
+    pub(crate) async fn workspace_require_admin(
+        &self,
+        wk_id: uuid::Uuid,
+        user_uid: uuid::Uuid,
+    ) -> Result<WkMemberModel, AppError> {
+        let member = self.workspace_member(wk_id, user_uid).await?;
+        if member.owner || member.admin {
+            Ok(member)
+        } else {
+            Err(AppError::PermissionDenied)
+        }
+    }
+
+    pub(crate) async fn workspace_require_owner(
+        &self,
+        wk_id: uuid::Uuid,
+        user_uid: uuid::Uuid,
+    ) -> Result<WkMemberModel, AppError> {
+        let member = self.workspace_member(wk_id, user_uid).await?;
+        if member.owner {
+            Ok(member)
+        } else {
+            Err(AppError::PermissionDenied)
+        }
+    }
+
+    async fn workspace_ensure_name_available(
+        &self,
+        name: &str,
+    ) -> Result<(), AppError> {
+        let current = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM workspace WHERE name = $1)",
+        )
+        .bind(name)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        let history = sqlx::query_scalar::<_, bool>(
+            "SELECT EXISTS(SELECT 1 FROM wk_history_name WHERE name = $1)",
+        )
+        .bind(name)
+        .fetch_one(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+
+        if current || history {
+            Err(AppError::Conflict(
+                "workspace name already exists".to_string(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    pub async fn workspace_my_inner(
+        &self,
+        user_id: uuid::Uuid,
+    ) -> Result<Vec<(String, Option<String>)>, AppError> {
+        let rows = sqlx::query_as::<_, (String, Option<String>)>(
+            "SELECT w.name, w.description \
+             FROM wk_member m \
+             INNER JOIN workspace w ON w.id = m.wk \
+             WHERE m.\"user\" = $1 AND m.leave_at IS NULL \
+             ORDER BY w.created_at DESC",
+        )
+        .bind(user_id)
+        .fetch_all(self.db.reader())
+        .await
+        .map_err(|e| AppError::DatabaseError(e.to_string()))?;
+        Ok(rows)
+    }
+}
diff --git a/lib/session/Cargo.toml b/lib/session/Cargo.toml
new file mode 100644
index 0000000..cde9dde
--- /dev/null
+++ b/lib/session/Cargo.toml
@@ -0,0 +1,33 @@
+[package]
+name = "session"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+[lib]
+path = "lib.rs"
+name = "session"
+[dependencies]
+actix-service = { workspace = true }
+actix-utils = { workspace = true }
+actix-web = { workspace = true, features = ["cookies", "secure-cookies"] }
+
+anyhow = { workspace = true }
+derive_more = { workspace = true, features = ["display", "error", "from"] }
+rand = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+uuid = { workspace = true,features = ["serde","v7","v4"] }
+redis = {  workspace = true, features = ["tokio-comp", "connection-manager", "cluster", "cluster-async"] }
+deadpool-redis = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "sync"] }
+tracing = { workspace = true }
+[lints]
+workspace = true
diff --git a/lib/session/config.rs b/lib/session/config.rs
new file mode 100644
index 0000000..a184d1f
--- /dev/null
+++ b/lib/session/config.rs
@@ -0,0 +1,223 @@
+use actix_web::cookie::{Key, SameSite, time::Duration};
+use derive_more::derive::From;
+
+use crate::{SessionMiddleware, storage::SessionStore};
+
+#[derive(Debug, Clone, From)]
+#[non_exhaustive]
+pub enum SessionLifecycle {
+    BrowserSession(BrowserSession),
+    PersistentSession(PersistentSession),
+}
+
+#[derive(Debug, Clone)]
+pub struct BrowserSession {
+    state_ttl: Duration,
+    state_ttl_extension_policy: TtlExtensionPolicy,
+}
+
+impl BrowserSession {
+    pub fn state_ttl(mut self, ttl: Duration) -> Self {
+        self.state_ttl = ttl;
+        self
+    }
+
+    pub fn state_ttl_extension_policy(
+        mut self,
+        ttl_extension_policy: TtlExtensionPolicy,
+    ) -> Self {
+        self.state_ttl_extension_policy = ttl_extension_policy;
+        self
+    }
+}
+
+impl Default for BrowserSession {
+    fn default() -> Self {
+        Self {
+            state_ttl: default_ttl(),
+            state_ttl_extension_policy: default_ttl_extension_policy(),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct PersistentSession {
+    session_ttl: Duration,
+    ttl_extension_policy: TtlExtensionPolicy,
+}
+
+impl PersistentSession {
+    #[doc(alias = "max_age", alias = "max age", alias = "expires")]
+    pub fn session_ttl(mut self, session_ttl: Duration) -> Self {
+        self.session_ttl = session_ttl;
+        self
+    }
+
+    pub fn session_ttl_extension_policy(
+        mut self,
+        ttl_extension_policy: TtlExtensionPolicy,
+    ) -> Self {
+        self.ttl_extension_policy = ttl_extension_policy;
+        self
+    }
+}
+
+impl Default for PersistentSession {
+    fn default() -> Self {
+        Self {
+            session_ttl: default_ttl(),
+            ttl_extension_policy: default_ttl_extension_policy(),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub enum TtlExtensionPolicy {
+    OnEveryRequest,
+    OnStateChanges,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum CookieContentSecurity {
+    Private,
+    Signed,
+}
+
+pub(crate) const fn default_ttl() -> Duration {
+    Duration::days(1)
+}
+
+pub(crate) const fn default_ttl_extension_policy() -> TtlExtensionPolicy {
+    TtlExtensionPolicy::OnStateChanges
+}
+
+#[must_use]
+pub struct SessionMiddlewareBuilder<Store: SessionStore> {
+    storage_backend: Store,
+    configuration: Configuration,
+}
+
+impl<Store: SessionStore> SessionMiddlewareBuilder<Store> {
+    pub(crate) fn new(store: Store, configuration: Configuration) -> Self {
+        Self {
+            storage_backend: store,
+            configuration,
+        }
+    }
+
+    pub fn cookie_name(mut self, name: String) -> Self {
+        self.configuration.cookie.name = name;
+        self
+    }
+
+    pub fn cookie_secure(mut self, secure: bool) -> Self {
+        self.configuration.cookie.secure = secure;
+        self
+    }
+
+    pub fn session_lifecycle<S: Into<SessionLifecycle>>(
+        mut self,
+        session_lifecycle: S,
+    ) -> Self {
+        match session_lifecycle.into() {
+            SessionLifecycle::BrowserSession(BrowserSession {
+                state_ttl,
+                state_ttl_extension_policy,
+            }) => {
+                self.configuration.cookie.max_age = None;
+                self.configuration.session.state_ttl = state_ttl;
+                self.configuration.ttl_extension_policy =
+                    state_ttl_extension_policy;
+            }
+            SessionLifecycle::PersistentSession(PersistentSession {
+                session_ttl,
+                ttl_extension_policy,
+            }) => {
+                self.configuration.cookie.max_age = Some(session_ttl);
+                self.configuration.session.state_ttl = session_ttl;
+                self.configuration.ttl_extension_policy = ttl_extension_policy;
+            }
+        }
+
+        self
+    }
+
+    pub fn cookie_same_site(mut self, same_site: SameSite) -> Self {
+        self.configuration.cookie.same_site = same_site;
+        self
+    }
+
+    pub fn cookie_path(mut self, path: String) -> Self {
+        self.configuration.cookie.path = path;
+        self
+    }
+
+    pub fn cookie_domain(mut self, domain: Option<String>) -> Self {
+        self.configuration.cookie.domain = domain;
+        self
+    }
+
+    pub fn cookie_content_security(
+        mut self,
+        content_security: CookieContentSecurity,
+    ) -> Self {
+        self.configuration.cookie.content_security = content_security;
+        self
+    }
+
+    pub fn cookie_http_only(mut self, http_only: bool) -> Self {
+        self.configuration.cookie.http_only = http_only;
+        self
+    }
+
+    #[must_use]
+    pub fn build(self) -> SessionMiddleware<Store> {
+        SessionMiddleware::from_parts(self.storage_backend, self.configuration)
+    }
+}
+
+#[derive(Clone)]
+pub(crate) struct Configuration {
+    pub(crate) cookie: CookieConfiguration,
+    pub(crate) session: SessionConfiguration,
+    pub(crate) ttl_extension_policy: TtlExtensionPolicy,
+}
+
+#[derive(Clone)]
+pub(crate) struct SessionConfiguration {
+    pub(crate) state_ttl: Duration,
+}
+
+#[derive(Clone)]
+pub(crate) struct CookieConfiguration {
+    pub(crate) secure: bool,
+    pub(crate) http_only: bool,
+    pub(crate) name: String,
+    pub(crate) same_site: SameSite,
+    pub(crate) path: String,
+    pub(crate) domain: Option<String>,
+    pub(crate) max_age: Option<Duration>,
+    pub(crate) content_security: CookieContentSecurity,
+    pub(crate) key: Key,
+}
+
+pub(crate) fn default_configuration(key: Key) -> Configuration {
+    Configuration {
+        cookie: CookieConfiguration {
+            secure: true,
+            http_only: true,
+            name: "id".into(),
+            same_site: SameSite::Lax,
+            path: "/".into(),
+            domain: None,
+            max_age: None,
+            content_security: CookieContentSecurity::Private,
+            key,
+        },
+        session: SessionConfiguration {
+            state_ttl: default_ttl(),
+        },
+        ttl_extension_policy: default_ttl_extension_policy(),
+    }
+}
diff --git a/lib/session/lib.rs b/lib/session/lib.rs
new file mode 100644
index 0000000..c306c16
--- /dev/null
+++ b/lib/session/lib.rs
@@ -0,0 +1,16 @@
+#![forbid(unsafe_code)]
+
+pub mod config;
+mod middleware;
+mod session;
+mod session_ext;
+pub mod storage;
+
+pub use self::{
+    middleware::SessionMiddleware,
+    session::{
+        Session, SessionGetError, SessionInsertError, SessionStatus,
+        SessionUser,
+    },
+    session_ext::SessionExt,
+};
diff --git a/lib/session/middleware.rs b/lib/session/middleware.rs
new file mode 100644
index 0000000..4473700
--- /dev/null
+++ b/lib/session/middleware.rs
@@ -0,0 +1,360 @@
+use std::{fmt, future::Future, pin::Pin, rc::Rc};
+
+use actix_utils::future::{Ready, ready};
+use actix_web::{
+    HttpResponse,
+    body::MessageBody,
+    cookie::{Cookie, CookieJar, Key},
+    dev::{
+        ResponseHead, Service, ServiceRequest, ServiceResponse, Transform,
+        forward_ready,
+    },
+    http::header::{HeaderValue, SET_COOKIE},
+};
+use anyhow::Context;
+use serde_json::{Map, Value};
+
+use crate::{
+    Session, SessionStatus,
+    config::{
+        self, Configuration, CookieConfiguration, CookieContentSecurity,
+        SessionMiddlewareBuilder, TtlExtensionPolicy,
+    },
+    storage::{LoadError, SessionKey, SessionStore},
+};
+
+#[derive(Clone)]
+pub struct SessionMiddleware<Store: SessionStore> {
+    storage_backend: Rc<Store>,
+    configuration: Rc<Configuration>,
+}
+
+impl<Store: SessionStore> SessionMiddleware<Store> {
+    pub fn new(store: Store, key: Key) -> Self {
+        Self::builder(store, key).build()
+    }
+
+    pub fn builder(store: Store, key: Key) -> SessionMiddlewareBuilder<Store> {
+        SessionMiddlewareBuilder::new(store, config::default_configuration(key))
+    }
+
+    pub(crate) fn from_parts(
+        store: Store,
+        configuration: Configuration,
+    ) -> Self {
+        Self {
+            storage_backend: Rc::new(store),
+            configuration: Rc::new(configuration),
+        }
+    }
+}
+
+impl<S, B, Store> Transform<S, ServiceRequest> for SessionMiddleware<Store>
+where
+    S: Service<
+            ServiceRequest,
+            Response = ServiceResponse<B>,
+            Error = actix_web::Error,
+        > + 'static,
+    S::Future: 'static,
+    B: MessageBody + 'static,
+    Store: SessionStore + 'static,
+{
+    type Response = ServiceResponse<B>;
+    type Error = actix_web::Error;
+    type Transform = InnerSessionMiddleware<S, Store>;
+    type InitError = ();
+    type Future = Ready<Result<Self::Transform, Self::InitError>>;
+
+    fn new_transform(&self, service: S) -> Self::Future {
+        ready(Ok(InnerSessionMiddleware {
+            service: Rc::new(service),
+            configuration: Rc::clone(&self.configuration),
+            storage_backend: Rc::clone(&self.storage_backend),
+        }))
+    }
+}
+
+fn e500<E: fmt::Debug + fmt::Display + 'static>(err: E) -> actix_web::Error {
+    actix_web::error::InternalError::from_response(
+        err,
+        HttpResponse::InternalServerError().finish(),
+    )
+    .into()
+}
+
+#[doc(hidden)]
+#[non_exhaustive]
+pub struct InnerSessionMiddleware<S, Store: SessionStore + 'static> {
+    service: Rc<S>,
+    configuration: Rc<Configuration>,
+    storage_backend: Rc<Store>,
+}
+
+impl<S, B, Store> Service<ServiceRequest> for InnerSessionMiddleware<S, Store>
+where
+    S: Service<
+            ServiceRequest,
+            Response = ServiceResponse<B>,
+            Error = actix_web::Error,
+        > + 'static,
+    S::Future: 'static,
+    Store: SessionStore + 'static,
+{
+    type Response = ServiceResponse<B>;
+    type Error = actix_web::Error;
+    #[allow(clippy::type_complexity)]
+    type Future =
+        Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
+
+    forward_ready!(service);
+
+    fn call(&self, mut req: ServiceRequest) -> Self::Future {
+        let service = Rc::clone(&self.service);
+        let storage_backend = Rc::clone(&self.storage_backend);
+        let configuration = Rc::clone(&self.configuration);
+
+        Box::pin(async move {
+            let session_key = extract_session_key(&req, &configuration.cookie);
+            let (session_key, session_state) =
+                load_session_state(session_key, storage_backend.as_ref())
+                    .await?;
+
+            Session::set_session(&mut req, session_state);
+
+            let mut res = service.call(req).await?;
+            let (status, session_state) = Session::get_changes(&mut res);
+
+            match session_key {
+                None => {
+                    if !session_state.is_empty() {
+                        let session_key = storage_backend
+                            .save(
+                                session_state,
+                                &configuration.session.state_ttl,
+                            )
+                            .await
+                            .map_err(e500)?;
+
+                        set_session_cookie(
+                            res.response_mut().head_mut(),
+                            session_key,
+                            &configuration.cookie,
+                        )
+                        .map_err(e500)?;
+                    }
+                }
+
+                Some(session_key) => {
+                    match status {
+                        SessionStatus::Changed => {
+                            let session_key = storage_backend
+                                .update(
+                                    session_key,
+                                    session_state,
+                                    &configuration.session.state_ttl,
+                                )
+                                .await
+                                .map_err(e500)?;
+
+                            set_session_cookie(
+                                res.response_mut().head_mut(),
+                                session_key,
+                                &configuration.cookie,
+                            )
+                            .map_err(e500)?;
+                        }
+
+                        SessionStatus::Purged => {
+                            storage_backend
+                                .delete(&session_key)
+                                .await
+                                .map_err(e500)?;
+
+                            delete_session_cookie(
+                                res.response_mut().head_mut(),
+                                &configuration.cookie,
+                            )
+                            .map_err(e500)?;
+                        }
+
+                        SessionStatus::Renewed => {
+                            storage_backend
+                                .delete(&session_key)
+                                .await
+                                .map_err(e500)?;
+
+                            let session_key = storage_backend
+                                .save(
+                                    session_state,
+                                    &configuration.session.state_ttl,
+                                )
+                                .await
+                                .map_err(e500)?;
+
+                            set_session_cookie(
+                                res.response_mut().head_mut(),
+                                session_key,
+                                &configuration.cookie,
+                            )
+                            .map_err(e500)?;
+                        }
+
+                        SessionStatus::Unchanged => {
+                            if matches!(
+                                configuration.ttl_extension_policy,
+                                TtlExtensionPolicy::OnEveryRequest
+                            ) {
+                                storage_backend
+                                    .update_ttl(
+                                        &session_key,
+                                        &configuration.session.state_ttl,
+                                    )
+                                    .await
+                                    .map_err(e500)?;
+
+                                if configuration.cookie.max_age.is_some() {
+                                    set_session_cookie(
+                                        res.response_mut().head_mut(),
+                                        session_key,
+                                        &configuration.cookie,
+                                    )
+                                    .map_err(e500)?;
+                                }
+                            }
+                        }
+                    };
+                }
+            }
+
+            Ok(res)
+        })
+    }
+}
+
+fn extract_session_key(
+    req: &ServiceRequest,
+    config: &CookieConfiguration,
+) -> Option<SessionKey> {
+    let cookies = match req.cookies() {
+        Ok(cookies) => cookies,
+        Err(_e) => {
+            return None;
+        }
+    };
+    let session_cookie = cookies
+        .iter()
+        .find(|&cookie| cookie.name() == config.name)?;
+
+    let mut jar = CookieJar::new();
+    jar.add_original(session_cookie.clone());
+
+    let verification_result = match config.content_security {
+        CookieContentSecurity::Signed => {
+            jar.signed(&config.key).get(&config.name)
+        }
+        CookieContentSecurity::Private => {
+            jar.private(&config.key).get(&config.name)
+        }
+    };
+
+    verification_result?.value().to_owned().try_into().ok()
+}
+
+async fn load_session_state<Store: SessionStore>(
+    session_key: Option<SessionKey>,
+    storage_backend: &Store,
+) -> Result<(Option<SessionKey>, Map<String, Value>), actix_web::Error> {
+    if let Some(session_key) = session_key {
+        match storage_backend.load(&session_key).await {
+            Ok(state) => {
+                if let Some(state) = state {
+                    Ok((Some(session_key), state))
+                } else {
+                    Ok((None, Map::new()))
+                }
+            }
+
+            Err(_err) => match _err {
+                LoadError::Deserialization(_err) => {
+                    Ok((Some(session_key), Map::new()))
+                }
+
+                LoadError::Other(err) => Err(e500(err)),
+            },
+        }
+    } else {
+        Ok((None, Map::new()))
+    }
+}
+
+fn set_session_cookie(
+    response: &mut ResponseHead,
+    session_key: SessionKey,
+    config: &CookieConfiguration,
+) -> Result<(), anyhow::Error> {
+    let value: String = session_key.into();
+    let mut cookie = Cookie::new(config.name.clone(), value);
+
+    cookie.set_secure(config.secure);
+    cookie.set_http_only(config.http_only);
+    cookie.set_same_site(config.same_site);
+    cookie.set_path(config.path.clone());
+
+    if let Some(max_age) = config.max_age {
+        cookie.set_max_age(max_age);
+    }
+
+    if let Some(ref domain) = config.domain {
+        cookie.set_domain(domain.clone());
+    }
+
+    let mut jar = CookieJar::new();
+    match config.content_security {
+        CookieContentSecurity::Signed => {
+            jar.signed_mut(&config.key).add(cookie)
+        }
+        CookieContentSecurity::Private => {
+            jar.private_mut(&config.key).add(cookie)
+        }
+    }
+
+    let cookie = jar
+        .delta()
+        .next()
+        .context("Failed to build session cookie")?;
+    let val = HeaderValue::from_str(&cookie.encoded().to_string()).context(
+        "Failed to attach a session cookie to the outgoing response",
+    )?;
+
+    response.headers_mut().append(SET_COOKIE, val);
+
+    Ok(())
+}
+
+fn delete_session_cookie(
+    response: &mut ResponseHead,
+    config: &CookieConfiguration,
+) -> Result<(), anyhow::Error> {
+    let removal_cookie = Cookie::build(config.name.clone(), "")
+        .path(config.path.clone())
+        .secure(config.secure)
+        .http_only(config.http_only)
+        .same_site(config.same_site);
+
+    let mut removal_cookie = if let Some(ref domain) = config.domain {
+        removal_cookie.domain(domain)
+    } else {
+        removal_cookie
+    }
+    .finish();
+
+    removal_cookie.make_removal();
+
+    let val = HeaderValue::from_str(&removal_cookie.to_string()).context(
+        "Failed to attach a session removal cookie to the outgoing response",
+    )?;
+    response.headers_mut().append(SET_COOKIE, val);
+
+    Ok(())
+}
diff --git a/lib/session/session.rs b/lib/session/session.rs
new file mode 100644
index 0000000..0ec888f
--- /dev/null
+++ b/lib/session/session.rs
@@ -0,0 +1,438 @@
+use std::{
+    cell::{Ref, RefCell},
+    convert::Infallible,
+    error::Error as StdError,
+    future::Future,
+    mem,
+    pin::Pin,
+    rc::Rc,
+};
+
+use actix_utils::future::{Ready, ready};
+use actix_web::{
+    FromRequest, HttpMessage, HttpRequest, HttpResponse, ResponseError,
+    body::BoxBody,
+    dev::{Extensions, Payload, ServiceRequest, ServiceResponse},
+};
+use anyhow::Context;
+use derive_more::derive::{Display, From};
+use serde::{Serialize, de::DeserializeOwned};
+use serde_json::{Map, Value};
+use uuid::Uuid;
+
+const SESSION_USER_KEY: &str = "session:user_uid";
+
+#[derive(Clone)]
+pub struct Session(Rc<RefCell<SessionInner>>);
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub enum SessionStatus {
+    Changed,
+    Purged,
+    Renewed,
+    #[default]
+    Unchanged,
+}
+
+#[derive(Default)]
+struct SessionInner {
+    state: Map<String, Value>,
+    status: SessionStatus,
+}
+
+impl Session {
+    pub fn get<T: DeserializeOwned>(
+        &self,
+        key: &str,
+    ) -> Result<Option<T>, SessionGetError> {
+        if let Some(value) = self.0.borrow().state.get(key) {
+            Ok(Some(
+                serde_json::from_value::<T>(value.clone())
+                    .with_context(|| {
+                        format!(
+                            "Failed to deserialize the JSON-encoded session data attached to key \
+                            `{}` as a `{}` type",
+                            key,
+                            std::any::type_name::<T>()
+                        )
+                    })
+                    .map_err(SessionGetError)?,
+            ))
+        } else {
+            Ok(None)
+        }
+    }
+
+    pub fn contains_key(&self, key: &str) -> bool {
+        self.0.borrow().state.contains_key(key)
+    }
+
+    pub fn entries(&self) -> Ref<'_, Map<String, Value>> {
+        Ref::map(self.0.borrow(), |inner| &inner.state)
+    }
+
+    pub fn status(&self) -> SessionStatus {
+        Ref::map(self.0.borrow(), |inner| &inner.status).clone()
+    }
+
+    pub fn insert<T: Serialize>(
+        &self,
+        key: impl Into<String>,
+        value: T,
+    ) -> Result<(), SessionInsertError> {
+        let mut inner = self.0.borrow_mut();
+
+        if inner.status != SessionStatus::Purged {
+            if inner.status != SessionStatus::Renewed {
+                inner.status = SessionStatus::Changed;
+            }
+
+            let key = key.into();
+            let val = serde_json::to_value(&value)
+                .with_context(|| {
+                    format!(
+                        "Failed to serialize the provided `{}` type instance as JSON in order to \
+                        attach as session data to the `{key}` key",
+                        std::any::type_name::<T>(),
+                    )
+                })
+                .map_err(SessionInsertError)?;
+
+            inner.state.insert(key, val);
+        }
+
+        Ok(())
+    }
+
+    pub fn update<T: Serialize + DeserializeOwned, F>(
+        &self,
+        key: impl Into<String>,
+        updater: F,
+    ) -> Result<(), SessionUpdateError>
+    where
+        F: FnOnce(T) -> T,
+    {
+        let mut inner = self.0.borrow_mut();
+        let key_str = key.into();
+
+        if let Some(val) = inner.state.get(&key_str) {
+            if inner.status == SessionStatus::Purged {
+                return Ok(());
+            }
+
+            let value = serde_json::from_value(val.clone())
+                .with_context(|| {
+                    format!(
+                        "Failed to deserialize the JSON-encoded session data attached to key \
+                        `{key_str}` as a `{}` type",
+                        std::any::type_name::<T>()
+                    )
+                })
+                .map_err(SessionUpdateError)?;
+
+            let val = serde_json::to_value(updater(value))
+                .with_context(|| {
+                    format!(
+                        "Failed to serialize the provided `{}` type instance as JSON in order to \
+                        attach as session data to the `{key_str}` key",
+                        std::any::type_name::<T>(),
+                    )
+                })
+                .map_err(SessionUpdateError)?;
+
+            if inner.status != SessionStatus::Renewed {
+                inner.status = SessionStatus::Changed;
+            }
+            inner.state.insert(key_str, val);
+        }
+
+        Ok(())
+    }
+
+    pub fn update_or<T: Serialize + DeserializeOwned, F>(
+        &self,
+        key: &str,
+        default_value: T,
+        updater: F,
+    ) -> Result<(), SessionUpdateError>
+    where
+        F: FnOnce(T) -> T,
+    {
+        if self.contains_key(key) {
+            self.update(key, updater)
+        } else {
+            self.insert(key, default_value)
+                .map_err(|err| SessionUpdateError(err.into()))
+        }
+    }
+
+    pub fn remove(&self, key: &str) -> Option<Value> {
+        let mut inner = self.0.borrow_mut();
+
+        if inner.status != SessionStatus::Purged {
+            if inner.status != SessionStatus::Renewed {
+                inner.status = SessionStatus::Changed;
+            }
+            return inner.state.remove(key);
+        }
+
+        None
+    }
+
+    pub fn remove_as<T: DeserializeOwned>(
+        &self,
+        key: &str,
+    ) -> Option<Result<T, Value>> {
+        self.remove(key).map(|value| {
+            match serde_json::from_value::<T>(value.clone()) {
+                Ok(val) => Ok(val),
+                Err(_err) => Err(value),
+            }
+        })
+    }
+
+    pub fn clear(&self) {
+        let mut inner = self.0.borrow_mut();
+
+        if inner.status != SessionStatus::Purged {
+            if inner.status != SessionStatus::Renewed {
+                inner.status = SessionStatus::Changed;
+            }
+            inner.state.clear()
+        }
+    }
+
+    pub fn purge(&self) {
+        let mut inner = self.0.borrow_mut();
+        inner.status = SessionStatus::Purged;
+        inner.state.clear();
+    }
+
+    pub fn renew(&self) {
+        let mut inner = self.0.borrow_mut();
+
+        if inner.status != SessionStatus::Purged {
+            inner.status = SessionStatus::Renewed;
+        }
+    }
+
+    pub fn user(&self) -> Option<Uuid> {
+        self.get::<Uuid>(SESSION_USER_KEY).ok().flatten()
+    }
+
+    pub fn set_user(&self, uid: Uuid) {
+        let _ = self.insert(SESSION_USER_KEY, uid);
+    }
+
+    pub fn clear_user(&self) {
+        let _ = self.remove(SESSION_USER_KEY);
+    }
+
+    pub fn ip_address(&self) -> Option<String> {
+        self.get::<String>("session:ip_address").ok().flatten()
+    }
+
+    pub fn user_agent(&self) -> Option<String> {
+        self.get::<String>("session:user_agent").ok().flatten()
+    }
+
+    pub fn set_request_info(req: &HttpRequest) {
+        let extensions = req.extensions_mut();
+        if let Some(inner) = extensions.get::<Rc<RefCell<SessionInner>>>() {
+            let mut inner = inner.borrow_mut();
+            let mut changed = false;
+            if let Some(ua) = req.headers().get("user-agent")
+                && let Ok(ua) = ua.to_str()
+            {
+                let _ = inner.state.insert(
+                    "session:user_agent".to_string(),
+                    serde_json::json!(ua),
+                );
+                changed = true;
+            }
+            let addr = req
+                .connection_info()
+                .realip_remote_addr()
+                .map(|s| s.to_string());
+            if let Some(ip) = addr {
+                let _ = inner.state.insert(
+                    "session:ip_address".to_string(),
+                    serde_json::json!(ip),
+                );
+                changed = true;
+            }
+            if changed && inner.status != SessionStatus::Renewed {
+                inner.status = SessionStatus::Changed;
+            }
+        }
+    }
+
+    #[allow(clippy::needless_pass_by_ref_mut)]
+    pub(crate) fn set_session(
+        req: &mut ServiceRequest,
+        data: impl IntoIterator<Item = (String, Value)>,
+    ) {
+        let session = Session::get_session(&mut req.extensions_mut());
+        let mut inner = session.0.borrow_mut();
+        inner.state.extend(data);
+    }
+
+    #[allow(clippy::needless_pass_by_ref_mut)]
+    pub(crate) fn get_changes<B>(
+        res: &mut ServiceResponse<B>,
+    ) -> (SessionStatus, Map<String, Value>) {
+        if let Some(s_impl) = res
+            .request()
+            .extensions()
+            .get::<Rc<RefCell<SessionInner>>>()
+        {
+            let state = mem::take(&mut s_impl.borrow_mut().state);
+            (s_impl.borrow().status.clone(), state)
+        } else {
+            (SessionStatus::Unchanged, Map::new())
+        }
+    }
+    pub fn no_op() -> Self {
+        Self(Rc::new(RefCell::new(SessionInner::default())))
+    }
+    pub fn get_session(extensions: &mut Extensions) -> Session {
+        if let Some(s_impl) = extensions.get::<Rc<RefCell<SessionInner>>>() {
+            return Session(Rc::clone(s_impl));
+        }
+
+        let inner = Rc::new(RefCell::new(SessionInner::default()));
+        extensions.insert(inner.clone());
+
+        Session(inner)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::{Session, SessionStatus, SessionUpdateError};
+
+    #[test]
+    fn update_marks_session_as_changed() -> Result<(), SessionUpdateError> {
+        let session = Session::no_op();
+        {
+            let mut inner = session.0.borrow_mut();
+            inner.state.insert("counter".to_string(), json!(1_u64));
+            inner.status = SessionStatus::Unchanged;
+        }
+
+        session.update("counter", |counter: u64| counter + 1)?;
+
+        assert_eq!(session.status(), SessionStatus::Changed);
+        assert_eq!(
+            session.0.borrow().state.get("counter"),
+            Some(&json!(2_u64))
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn update_preserves_renewed_status() -> Result<(), SessionUpdateError> {
+        let session = Session::no_op();
+        {
+            let mut inner = session.0.borrow_mut();
+            inner.state.insert("counter".to_string(), json!(1_u64));
+            inner.status = SessionStatus::Renewed;
+        }
+
+        session.update("counter", |counter: u64| counter + 1)?;
+
+        assert_eq!(session.status(), SessionStatus::Renewed);
+        assert_eq!(
+            session.0.borrow().state.get("counter"),
+            Some(&json!(2_u64))
+        );
+        Ok(())
+    }
+}
+
+impl FromRequest for Session {
+    type Error = Infallible;
+    type Future = Ready<Result<Self, Self::Error>>;
+
+    #[inline]
+    fn from_request(req: &HttpRequest, _: &mut Payload) -> Self::Future {
+        ready(Ok(Session::get_session(&mut req.extensions_mut())))
+    }
+}
+#[derive(Clone, Copy)]
+pub struct SessionUser(pub Uuid);
+
+impl FromRequest for SessionUser {
+    type Error = SessionGetError;
+    type Future = Pin<Box<dyn Future<Output = Result<Self, Self::Error>>>>;
+
+    fn from_request(req: &HttpRequest, _: &mut Payload) -> Self::Future {
+        let req = req.clone();
+        Box::pin(async move {
+            let uid = {
+                let mut extensions = req.extensions_mut();
+                let session = Session::get_session(&mut extensions);
+                session.user().ok_or_else(|| {
+                    SessionGetError(anyhow::anyhow!("not authenticated"))
+                })?
+            };
+            Ok(SessionUser(uid))
+        })
+    }
+}
+
+#[derive(Debug, Display, From)]
+#[display("{_0}")]
+pub struct SessionGetError(anyhow::Error);
+
+impl StdError for SessionGetError {
+    fn source(&self) -> Option<&(dyn StdError + 'static)> {
+        Some(self.0.as_ref())
+    }
+}
+
+impl ResponseError for SessionGetError {
+    fn error_response(&self) -> HttpResponse<BoxBody> {
+        HttpResponse::build(self.status_code())
+            .content_type("text/plain")
+            .body(self.to_string())
+    }
+}
+
+#[derive(Debug, Display, From)]
+#[display("{_0}")]
+pub struct SessionInsertError(anyhow::Error);
+
+impl StdError for SessionInsertError {
+    fn source(&self) -> Option<&(dyn StdError + 'static)> {
+        Some(self.0.as_ref())
+    }
+}
+
+impl ResponseError for SessionInsertError {
+    fn error_response(&self) -> HttpResponse<BoxBody> {
+        HttpResponse::build(self.status_code())
+            .content_type("text/plain")
+            .body(self.to_string())
+    }
+}
+
+#[derive(Debug, Display, From)]
+#[display("{_0}")]
+pub struct SessionUpdateError(anyhow::Error);
+
+impl StdError for SessionUpdateError {
+    fn source(&self) -> Option<&(dyn StdError + 'static)> {
+        Some(self.0.as_ref())
+    }
+}
+
+impl ResponseError for SessionUpdateError {
+    fn error_response(&self) -> HttpResponse<BoxBody> {
+        HttpResponse::build(self.status_code())
+            .content_type("text/plain")
+            .body(self.to_string())
+    }
+}
diff --git a/lib/session/session_ext.rs b/lib/session/session_ext.rs
new file mode 100644
index 0000000..318fb2f
--- /dev/null
+++ b/lib/session/session_ext.rs
@@ -0,0 +1,35 @@
+use actix_web::{
+    HttpMessage, HttpRequest,
+    dev::{ServiceRequest, ServiceResponse},
+    guard::GuardContext,
+};
+
+use crate::Session;
+
+pub trait SessionExt {
+    fn get_session(&self) -> Session;
+}
+
+impl SessionExt for HttpRequest {
+    fn get_session(&self) -> Session {
+        Session::get_session(&mut self.extensions_mut())
+    }
+}
+
+impl SessionExt for ServiceRequest {
+    fn get_session(&self) -> Session {
+        Session::get_session(&mut self.extensions_mut())
+    }
+}
+
+impl SessionExt for ServiceResponse {
+    fn get_session(&self) -> Session {
+        self.request().get_session()
+    }
+}
+
+impl SessionExt for GuardContext<'_> {
+    fn get_session(&self) -> Session {
+        Session::get_session(&mut self.req_data_mut())
+    }
+}
diff --git a/lib/session/storage/format.rs b/lib/session/storage/format.rs
new file mode 100644
index 0000000..b6e8df1
--- /dev/null
+++ b/lib/session/storage/format.rs
@@ -0,0 +1,79 @@
+use std::collections::HashMap;
+
+use serde::ser::{Serialize, SerializeMap, Serializer};
+use serde_json::{Map, Value};
+
+use super::interface::SessionState;
+
+const SESSION_STATE_FORMAT_VERSION: u8 = 1;
+
+#[derive(Debug)]
+struct StoredSessionStateRef<'a> {
+    state: &'a SessionState,
+}
+
+impl Serialize for StoredSessionStateRef<'_> {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        let mut map = serializer.serialize_map(Some(2))?;
+        map.serialize_entry("v", &SESSION_STATE_FORMAT_VERSION)?;
+        map.serialize_entry("state", self.state)?;
+        map.end()
+    }
+}
+
+pub(crate) fn serialize_session_state(
+    session_state: &SessionState,
+) -> Result<String, anyhow::Error> {
+    let stored = StoredSessionStateRef {
+        state: session_state,
+    };
+
+    serde_json::to_string(&stored).map_err(anyhow::Error::new)
+}
+
+pub(crate) fn deserialize_session_state(
+    value: &str,
+) -> Result<SessionState, anyhow::Error> {
+    let value = serde_json::from_str::<Value>(value)?;
+
+    let Value::Object(mut obj) = value else {
+        anyhow::bail!("Session state is not a JSON object");
+    };
+
+    if matches!(obj.get("state"), Some(Value::Object(_)))
+        && let Some(Value::Number(v)) = obj.get("v")
+    {
+        let v = v.as_u64().ok_or_else(|| {
+            anyhow::anyhow!("Invalid session state format version")
+        })?;
+        let v = u8::try_from(v).map_err(|_| {
+            anyhow::anyhow!("Invalid session state format version")
+        })?;
+        anyhow::ensure!(
+            v == SESSION_STATE_FORMAT_VERSION,
+            "Unsupported session state format version: {}",
+            v
+        );
+
+        let Some(Value::Object(state)) = obj.remove("state") else {
+            unreachable!("`state` was checked to be an object above");
+        };
+        return Ok(state);
+    }
+
+    if obj.values().all(Value::is_string) {
+        let legacy: HashMap<String, String> =
+            serde_json::from_value(Value::Object(obj))?;
+        let mut migrated: Map<String, Value> = Map::new();
+        for (key, json_encoded) in legacy {
+            migrated.insert(key, serde_json::from_str::<Value>(&json_encoded)?);
+        }
+
+        return Ok(migrated);
+    }
+
+    Ok(obj)
+}
diff --git a/lib/session/storage/interface.rs b/lib/session/storage/interface.rs
new file mode 100644
index 0000000..d3f6b6f
--- /dev/null
+++ b/lib/session/storage/interface.rs
@@ -0,0 +1,94 @@
+use std::future::Future;
+
+use actix_web::cookie::time::Duration;
+use derive_more::derive::Display;
+use serde_json::{Map, Value};
+
+use super::SessionKey;
+
+pub(crate) type SessionState = Map<String, Value>;
+
+pub trait SessionStore {
+    fn load(
+        &self,
+        session_key: &SessionKey,
+    ) -> impl Future<Output = Result<Option<SessionState>, LoadError>>;
+
+    fn save(
+        &self,
+        session_state: SessionState,
+        ttl: &Duration,
+    ) -> impl Future<Output = Result<SessionKey, SaveError>>;
+
+    fn update(
+        &self,
+        session_key: SessionKey,
+        session_state: SessionState,
+        ttl: &Duration,
+    ) -> impl Future<Output = Result<SessionKey, UpdateError>>;
+
+    fn update_ttl(
+        &self,
+        session_key: &SessionKey,
+        ttl: &Duration,
+    ) -> impl Future<Output = Result<(), anyhow::Error>>;
+
+    fn delete(
+        &self,
+        session_key: &SessionKey,
+    ) -> impl Future<Output = Result<(), anyhow::Error>>;
+}
+
+#[derive(Debug, Display)]
+pub enum LoadError {
+    #[display("Failed to deserialize session state")]
+    Deserialization(anyhow::Error),
+
+    #[display("Something went wrong when retrieving the session state")]
+    Other(anyhow::Error),
+}
+
+impl std::error::Error for LoadError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Deserialization(err) => Some(err.as_ref()),
+            Self::Other(err) => Some(err.as_ref()),
+        }
+    }
+}
+
+#[derive(Debug, Display)]
+pub enum SaveError {
+    #[display("Failed to serialize session state")]
+    Serialization(anyhow::Error),
+
+    #[display("Something went wrong when persisting the session state")]
+    Other(anyhow::Error),
+}
+
+impl std::error::Error for SaveError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Serialization(err) => Some(err.as_ref()),
+            Self::Other(err) => Some(err.as_ref()),
+        }
+    }
+}
+
+#[derive(Debug, Display)]
+pub enum UpdateError {
+    #[display("Failed to serialize session state")]
+    Serialization(anyhow::Error),
+
+    #[display("Something went wrong when updating the session state.")]
+    Other(anyhow::Error),
+}
+
+impl std::error::Error for UpdateError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Self::Serialization(err) => Some(err.as_ref()),
+            Self::Other(err) => Some(err.as_ref()),
+        }
+    }
+}
diff --git a/lib/session/storage/mod.rs b/lib/session/storage/mod.rs
new file mode 100644
index 0000000..3f169fc
--- /dev/null
+++ b/lib/session/storage/mod.rs
@@ -0,0 +1,12 @@
+mod format;
+mod interface;
+mod redis_cluster;
+mod session_key;
+mod utils;
+
+pub use self::{
+    interface::{LoadError, SaveError, SessionStore, UpdateError},
+    redis_cluster::RedisClusterSessionStore,
+    session_key::SessionKey,
+    utils::generate_session_key,
+};
diff --git a/lib/session/storage/redis_cluster.rs b/lib/session/storage/redis_cluster.rs
new file mode 100644
index 0000000..71454ca
--- /dev/null
+++ b/lib/session/storage/redis_cluster.rs
@@ -0,0 +1,297 @@
+use std::{sync::Arc, time::Duration as StdDuration};
+
+use actix_web::cookie::time::Duration;
+use redis::{
+    cluster::{ClusterClient, ClusterClientBuilder},
+    cluster_async::ClusterConnection,
+};
+use tokio::sync::Mutex;
+
+use super::SessionKey;
+use crate::storage::{
+    SessionStore,
+    format::{deserialize_session_state, serialize_session_state},
+    interface::{LoadError, SaveError, SessionState, UpdateError},
+    utils::generate_session_key,
+};
+
+#[derive(Clone)]
+pub struct RedisClusterSessionStore {
+    client: ClusterClient,
+    connection: Arc<Mutex<ClusterConnection>>,
+    configuration: CacheConfiguration,
+}
+
+#[derive(Clone)]
+struct CacheConfiguration {
+    cache_keygen: Arc<dyn Fn(&str) -> String + Send + Sync>,
+}
+
+impl Default for CacheConfiguration {
+    fn default() -> Self {
+        Self {
+            cache_keygen: Arc::new(str::to_owned),
+        }
+    }
+}
+
+impl RedisClusterSessionStore {
+    const DEFAULT_CONNECTION_TIMEOUT: StdDuration = StdDuration::from_secs(2);
+    const DEFAULT_RESPONSE_TIMEOUT: StdDuration = StdDuration::from_secs(2);
+    const DEFAULT_COMMAND_TIMEOUT: StdDuration = StdDuration::from_secs(3);
+    const DEFAULT_RETRIES: u32 = 1;
+    const DEFAULT_RETRY_MIN_WAIT_MS: u64 = 25;
+    const DEFAULT_RETRY_MAX_WAIT_MS: u64 = 100;
+    const DEFAULT_RETRY_FACTOR: u64 = 10;
+    const DEFAULT_RETRY_EXPONENT_BASE: u64 = 2;
+
+    pub fn builder(
+        connection_strings: Vec<String>,
+    ) -> RedisClusterSessionStoreBuilder {
+        RedisClusterSessionStoreBuilder {
+            configuration: CacheConfiguration::default(),
+            connection_strings,
+        }
+    }
+
+    pub async fn new(
+        connection_strings: Vec<String>,
+    ) -> anyhow::Result<RedisClusterSessionStore> {
+        Self::builder(connection_strings).build().await
+    }
+
+    fn client_builder(connection_strings: Vec<String>) -> ClusterClientBuilder {
+        ClusterClient::builder(connection_strings)
+            .connection_timeout(Self::DEFAULT_CONNECTION_TIMEOUT)
+            .response_timeout(Self::DEFAULT_RESPONSE_TIMEOUT)
+            .retries(Self::DEFAULT_RETRIES)
+            .min_retry_wait(Self::DEFAULT_RETRY_MIN_WAIT_MS)
+            .max_retry_wait(Self::DEFAULT_RETRY_MAX_WAIT_MS)
+            .retry_wait_formula(
+                Self::DEFAULT_RETRY_FACTOR,
+                Self::DEFAULT_RETRY_EXPONENT_BASE,
+            )
+    }
+
+    async fn connect(
+        client: &ClusterClient,
+    ) -> anyhow::Result<ClusterConnection> {
+        let started = std::time::Instant::now();
+        let connection = tokio::time::timeout(
+            Self::DEFAULT_COMMAND_TIMEOUT,
+            client.get_async_connection(),
+        )
+        .await
+        .map_err(|_| anyhow::anyhow!("session redis async connect timed out"))?
+        .map_err(|e| anyhow::anyhow!(e))?;
+
+        tracing::debug!(
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "session redis async connect finished"
+        );
+        Ok(connection)
+    }
+
+    async fn execute_cmd<T, F>(
+        &self,
+        op_name: &'static str,
+        make_cmd: F,
+    ) -> anyhow::Result<T>
+    where
+        T: redis::FromRedisValue,
+        F: Fn() -> redis::Cmd,
+    {
+        let first_try: anyhow::Result<T> = {
+            let mut connection = self.connection.lock().await;
+            let started = std::time::Instant::now();
+            tracing::debug!(op = op_name, "session redis command start");
+            match tokio::time::timeout(
+                Self::DEFAULT_COMMAND_TIMEOUT,
+                make_cmd().query_async(&mut *connection),
+            )
+            .await
+            .map_err(|_| anyhow::anyhow!("session redis command timed out"))?
+            {
+                Ok(value) => {
+                    tracing::debug!(
+                        op = op_name,
+                        elapsed_ms = started.elapsed().as_millis() as u64,
+                        "session redis command finished"
+                    );
+                    return Ok(value);
+                }
+                Err(err) => Err(anyhow::anyhow!(err)),
+            }
+        };
+
+        if let Err(error) = &first_try {
+            tracing::warn!(op = op_name, error = %error, "session redis command failed, reconnecting");
+        }
+
+        let new_connection = Self::connect(&self.client).await?;
+        {
+            let mut connection = self.connection.lock().await;
+            *connection = new_connection;
+        }
+
+        let mut connection = self.connection.lock().await;
+        let started = std::time::Instant::now();
+        tracing::debug!(op = op_name, "session redis command retry start");
+        let result = tokio::time::timeout(
+            Self::DEFAULT_COMMAND_TIMEOUT,
+            make_cmd().query_async(&mut *connection),
+        )
+        .await
+        .map_err(|_| anyhow::anyhow!("session redis command retry timed out"))?
+        .map_err(|e| anyhow::anyhow!(e))?;
+        tracing::debug!(
+            op = op_name,
+            elapsed_ms = started.elapsed().as_millis() as u64,
+            "session redis command retry finished"
+        );
+        Ok(result)
+    }
+
+    fn ttl_seconds(ttl: &Duration) -> anyhow::Result<u64> {
+        let ttl_secs = ttl.whole_seconds();
+        if ttl_secs <= 0 {
+            anyhow::bail!("session TTL must be positive");
+        }
+        u64::try_from(ttl_secs).map_err(anyhow::Error::new)
+    }
+}
+
+#[must_use]
+pub struct RedisClusterSessionStoreBuilder {
+    configuration: CacheConfiguration,
+    connection_strings: Vec<String>,
+}
+
+impl RedisClusterSessionStoreBuilder {
+    pub fn cache_keygen<F>(mut self, keygen: F) -> Self
+    where
+        F: Fn(&str) -> String + 'static + Send + Sync,
+    {
+        self.configuration.cache_keygen = Arc::new(keygen);
+        self
+    }
+
+    pub async fn build(self) -> anyhow::Result<RedisClusterSessionStore> {
+        let client =
+            RedisClusterSessionStore::client_builder(self.connection_strings)
+                .build()?;
+        let connection = RedisClusterSessionStore::connect(&client).await?;
+
+        Ok(RedisClusterSessionStore {
+            client,
+            connection: Arc::new(Mutex::new(connection)),
+            configuration: self.configuration,
+        })
+    }
+}
+
+impl SessionStore for RedisClusterSessionStore {
+    async fn load(
+        &self,
+        session_key: &SessionKey,
+    ) -> Result<Option<SessionState>, LoadError> {
+        let cache_key =
+            self.configuration.cache_keygen.as_ref()(session_key.as_ref());
+        let value: Option<String> = self
+            .execute_cmd("get", move || {
+                let mut cmd = redis::cmd("GET");
+                cmd.arg(&cache_key);
+                cmd
+            })
+            .await
+            .map_err(LoadError::Other)?;
+
+        match value {
+            None => Ok(None),
+            Some(value) => Ok(Some(
+                deserialize_session_state(&value)
+                    .map_err(LoadError::Deserialization)?,
+            )),
+        }
+    }
+
+    async fn save(
+        &self,
+        session_state: SessionState,
+        ttl: &Duration,
+    ) -> Result<SessionKey, SaveError> {
+        let body = serialize_session_state(&session_state)
+            .map_err(SaveError::Serialization)?;
+        let session_key = generate_session_key();
+        let cache_key =
+            self.configuration.cache_keygen.as_ref()(session_key.as_ref());
+        let ttl_secs = Self::ttl_seconds(ttl).map_err(SaveError::Other)?;
+
+        self.execute_cmd::<(), _>("set_ex", move || {
+            let mut cmd = redis::cmd("SETEX");
+            cmd.arg(&cache_key).arg(ttl_secs).arg(&body);
+            cmd
+        })
+        .await
+        .map_err(SaveError::Other)?;
+
+        Ok(session_key)
+    }
+
+    async fn update(
+        &self,
+        session_key: SessionKey,
+        session_state: SessionState,
+        ttl: &Duration,
+    ) -> Result<SessionKey, UpdateError> {
+        let body = serialize_session_state(&session_state)
+            .map_err(UpdateError::Serialization)?;
+        let cache_key =
+            self.configuration.cache_keygen.as_ref()(session_key.as_ref());
+        let ttl_secs = Self::ttl_seconds(ttl).map_err(UpdateError::Other)?;
+
+        self.execute_cmd::<(), _>("set_ex", move || {
+            let mut cmd = redis::cmd("SETEX");
+            cmd.arg(&cache_key).arg(ttl_secs).arg(&body);
+            cmd
+        })
+        .await
+        .map_err(UpdateError::Other)?;
+
+        Ok(session_key)
+    }
+
+    async fn update_ttl(
+        &self,
+        session_key: &SessionKey,
+        ttl: &Duration,
+    ) -> anyhow::Result<()> {
+        let cache_key =
+            self.configuration.cache_keygen.as_ref()(session_key.as_ref());
+        let ttl_secs = Self::ttl_seconds(ttl)?;
+
+        self.execute_cmd("expire", move || {
+            let mut cmd = redis::cmd("EXPIRE");
+            cmd.arg(&cache_key).arg(ttl_secs);
+            cmd
+        })
+        .await
+        .map(|_: bool| ())
+    }
+
+    async fn delete(
+        &self,
+        session_key: &SessionKey,
+    ) -> Result<(), anyhow::Error> {
+        let cache_key =
+            self.configuration.cache_keygen.as_ref()(session_key.as_ref());
+
+        self.execute_cmd("del", move || {
+            let mut cmd = redis::cmd("DEL");
+            cmd.arg(&cache_key);
+            cmd
+        })
+        .await
+        .map(|_: i64| ())
+    }
+}
diff --git a/lib/session/storage/session_key.rs b/lib/session/storage/session_key.rs
new file mode 100644
index 0000000..0704df4
--- /dev/null
+++ b/lib/session/storage/session_key.rs
@@ -0,0 +1,48 @@
+use derive_more::derive::{Display, From};
+
+#[derive(Debug, PartialEq, Eq)]
+pub struct SessionKey(String);
+
+impl TryFrom<String> for SessionKey {
+    type Error = InvalidSessionKeyError;
+
+    fn try_from(val: String) -> Result<Self, Self::Error> {
+        if val.len() > 4064 {
+            return Err(anyhow::anyhow!(
+                "The session key is bigger than 4064 bytes, the upper limit on cookie content."
+            )
+            .into());
+        }
+
+        if val.contains('\0') {
+            return Err(anyhow::anyhow!(
+                "The session key contains null bytes which are not allowed."
+            )
+            .into());
+        }
+
+        Ok(SessionKey(val))
+    }
+}
+
+impl AsRef<str> for SessionKey {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl From<SessionKey> for String {
+    fn from(key: SessionKey) -> Self {
+        key.0
+    }
+}
+
+#[derive(Debug, Display, From)]
+#[display("The provided string is not a valid session key")]
+pub struct InvalidSessionKeyError(anyhow::Error);
+
+impl std::error::Error for InvalidSessionKeyError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        Some(self.0.as_ref())
+    }
+}
diff --git a/lib/session/storage/utils.rs b/lib/session/storage/utils.rs
new file mode 100644
index 0000000..0129b71
--- /dev/null
+++ b/lib/session/storage/utils.rs
@@ -0,0 +1,12 @@
+use rand::distr::{Alphanumeric, SampleString as _};
+
+use crate::storage::SessionKey;
+
+pub fn generate_session_key() -> SessionKey {
+    match Alphanumeric.sample_string(&mut rand::rng(), 64).try_into() {
+        Ok(session_key) => session_key,
+        Err(_error) => unreachable!(
+            "64 alphanumeric characters are always a valid session key"
+        ),
+    }
+}
diff --git a/lib/socketio/Cargo.toml b/lib/socketio/Cargo.toml
new file mode 100644
index 0000000..58f3373
--- /dev/null
+++ b/lib/socketio/Cargo.toml
@@ -0,0 +1,36 @@
+[package]
+name = "socketio"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+[lib]
+path = "lib.rs"
+name = "socketio"
+[dependencies]
+actix-web = { workspace = true }
+actix-ws = "0.4.0"
+async-nats = { workspace = true }
+async-trait = { workspace = true }
+base64 = { workspace = true }
+deadpool-redis = { workspace = true }
+futures-util = { workspace = true }
+redis = { workspace = true, features = ["cluster-async", "aio", "tokio-comp"] }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+session = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["macros", "sync", "time"] }
+tracing = { workspace = true }
+uuid = { workspace = true, features = ["v4"] }
+
+[lints]
+workspace = true
diff --git a/lib/socketio/actix.rs b/lib/socketio/actix.rs
new file mode 100644
index 0000000..a3e6585
--- /dev/null
+++ b/lib/socketio/actix.rs
@@ -0,0 +1,394 @@
+use std::sync::Arc;
+use std::sync::atomic::Ordering;
+
+use actix_web::{
+    Error, HttpRequest, HttpResponse,
+    error::{ErrorBadRequest, ErrorInternalServerError, ErrorNotFound},
+    http::header,
+    web::{self, Bytes, Data, Payload, ServiceConfig},
+};
+use futures_util::StreamExt;
+use serde_json::json;
+use session::SessionExt;
+
+use crate::{
+    engine_packet::{
+        EnginePacket, SocketPayload, decode_engine_payload,
+        decode_engine_text_packet, encode_engine_packet, encode_engine_payload,
+    },
+    error::SocketIoError,
+    server::SocketIo,
+    session::{Session, Transport},
+    socket::DisconnectReason,
+};
+struct ActiveGuard(Arc<std::sync::atomic::AtomicBool>);
+
+impl Drop for ActiveGuard {
+    fn drop(&mut self) {
+        self.0.store(false, Ordering::Release);
+    }
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct EngineQuery {
+    #[serde(rename = "EIO")]
+    eio: Option<String>,
+    transport: Option<String>,
+    sid: Option<String>,
+}
+
+pub fn configure(cfg: &mut ServiceConfig, io: SocketIo) {
+    let path = io.config().path.clone();
+    configure_at(cfg, path, io);
+}
+
+pub fn configure_at(
+    cfg: &mut ServiceConfig,
+    path: impl Into<String>,
+    io: SocketIo,
+) {
+    cfg.app_data(Data::new(io)).service(
+        web::resource(path.into())
+            .route(web::get().to(engine_get))
+            .route(web::post().to(engine_post)),
+    );
+}
+
+async fn engine_get(
+    io: Data<SocketIo>,
+    req: HttpRequest,
+    stream: Payload,
+    query: web::Query<EngineQuery>,
+) -> Result<HttpResponse, Error> {
+    validate_eio(&query)?;
+
+    match query.transport.as_deref() {
+        Some("polling") if query.sid.is_none() => polling_open(io, &req).await,
+        Some("polling") => polling_get(io, query.sid.as_deref()).await,
+        Some("websocket") => {
+            websocket_open(io, req, stream, query.sid.clone()).await
+        }
+        _ => Err(ErrorBadRequest("unsupported transport")),
+    }
+}
+
+async fn engine_post(
+    io: Data<SocketIo>,
+    query: web::Query<EngineQuery>,
+    body: Bytes,
+) -> Result<HttpResponse, Error> {
+    validate_eio(&query)?;
+    if query.transport.as_deref() != Some("polling") {
+        return Err(ErrorBadRequest("unsupported transport"));
+    }
+    if body.len() > io.config().max_payload {
+        return Err(ErrorBadRequest("payload too large"));
+    }
+
+    let sid = query
+        .sid
+        .as_deref()
+        .ok_or_else(|| ErrorBadRequest("missing sid"))?;
+    validate_sid(sid)?;
+    let session = io.session(sid).await.ok_or_else(|| ErrorNotFound("sid"))?;
+    if session.post_active.compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed).is_err() {
+        io.remove_session(&session, DisconnectReason::TransportClosed)
+            .await;
+        return Err(ErrorBadRequest("overlapping post request"));
+    }
+
+    let _guard = ActiveGuard(session.post_active.clone());
+    handle_polling_body(&io, session, &body).await?;
+
+    Ok(HttpResponse::Ok()
+        .insert_header((header::CONTENT_TYPE, "text/plain; charset=UTF-8"))
+        .body("ok"))
+}
+
+async fn handle_polling_body(
+    io: &SocketIo,
+    session: Arc<Session>,
+    body: &Bytes,
+) -> Result<(), Error> {
+    touch_session(&session).await;
+    let payload = std::str::from_utf8(body).map_err(ErrorBadRequest)?;
+    let packets = decode_engine_payload(payload).map_err(map_socket_error)?;
+    for packet in packets {
+        handle_engine_packet(io, session.clone(), packet).await?;
+    }
+    Ok(())
+}
+
+async fn polling_open(
+    io: Data<SocketIo>,
+    req: &HttpRequest,
+) -> Result<HttpResponse, Error> {
+    let session = Session::new(req.get_session().user());
+    let sid = session.engine_id.clone();
+    io.insert_session(session).await;
+
+    let open = json!({
+        "sid": sid,
+        "upgrades": ["websocket"],
+        "pingInterval": io.config().ping_interval.as_millis(),
+        "pingTimeout": io.config().ping_timeout.as_millis(),
+        "maxPayload": io.config().max_payload
+    });
+
+    Ok(text_response(encode_engine_packet(
+        &EnginePacket::Open(open),
+        true,
+    )))
+}
+
+async fn polling_get(
+    io: Data<SocketIo>,
+    sid: Option<&str>,
+) -> Result<HttpResponse, Error> {
+    let sid = sid.ok_or_else(|| ErrorBadRequest("missing sid"))?;
+    validate_sid(sid)?;
+    let session = io.session(sid).await.ok_or_else(|| ErrorNotFound("sid"))?;
+    if session.get_active.compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed).is_err() {
+        io.remove_session(&session, DisconnectReason::TransportClosed)
+            .await;
+        return Err(ErrorBadRequest("overlapping get request"));
+    }
+
+    let _guard = ActiveGuard(session.get_active.clone());
+    loop {
+        let packets = session.drain().await;
+        if !packets.is_empty() {
+            return Ok(text_response(encode_engine_payload(&packets, true)));
+        }
+        tokio::select! {
+            () = session.notify.notified() => {
+            }
+            () = tokio::time::sleep(io.config().ping_interval) => {
+                return Ok(text_response(encode_engine_payload(
+                    &[EnginePacket::Ping(None)], true,
+                )));
+            }
+        }
+    }
+}
+
+async fn websocket_open(
+    io: Data<SocketIo>,
+    req: HttpRequest,
+    stream: Payload,
+    sid: Option<String>,
+) -> Result<HttpResponse, Error> {
+    let direct_websocket = sid.is_none();
+    let session = match sid {
+        Some(ref sid) => {
+            validate_sid(sid)?;
+            io.session(sid).await.ok_or_else(|| ErrorNotFound("sid"))?
+        }
+        None => {
+            let session = Session::new(req.get_session().user());
+            io.insert_session(session.clone()).await;
+            session
+        }
+    };
+
+    let (response, mut ws_session, messages) = actix_ws::handle(&req, stream)?;
+    let io = io.get_ref().clone();
+
+    actix_web::rt::spawn(async move {
+        if direct_websocket {
+            *session.transport.lock().await = Transport::WebSocket;
+            let open = json!({
+                "sid": session.engine_id,
+                "upgrades": [],
+                "pingInterval": io.config().ping_interval.as_millis(),
+                "pingTimeout": io.config().ping_timeout.as_millis(),
+                "maxPayload": io.config().max_payload
+            });
+            if ws_session
+                .text(encode_engine_packet(&EnginePacket::Open(open), false))
+                .await
+                .is_err()
+            {
+                io.remove_session(&session, DisconnectReason::TransportClosed)
+                    .await;
+                return;
+            }
+        }
+
+        websocket_loop(io, session, ws_session, messages, direct_websocket)
+            .await;
+    });
+
+    Ok(response)
+}
+
+async fn websocket_loop(
+    io: SocketIo,
+    session: Arc<Session>,
+    mut ws_session: actix_ws::Session,
+    mut messages: actix_ws::MessageStream,
+    mut upgraded: bool,
+) {
+    let mut heartbeat = tokio::time::interval_at(
+        tokio::time::Instant::now() + io.config().ping_interval,
+        io.config().ping_interval,
+    );
+
+    loop {
+        tokio::select! {
+            message = messages.next() => {
+                match message {
+                    Some(Ok(actix_ws::Message::Text(text))) => {
+                        touch_session(&session).await;
+                        match decode_engine_text_packet(text.as_ref()) {
+                            Ok(EnginePacket::Ping(Some(value))) if value == "probe" && !upgraded => {
+                                if ws_session.text("3probe").await.is_err() {
+                                    break;
+                                }
+                            }
+                            Ok(EnginePacket::Upgrade) if !upgraded => {
+                                *session.transport.lock().await = Transport::WebSocket;
+                                upgraded = true;
+                            }
+                            Ok(packet) => {
+                                if handle_engine_packet(&io, session.clone(), packet).await.is_err() {
+                                    break;
+                                }
+                            }
+                            Err(_) => break,
+                        }
+                    }
+                    Some(Ok(actix_ws::Message::Binary(bytes))) => {
+                        touch_session(&session).await;
+                        if handle_engine_packet(
+                            &io,
+                            session.clone(),
+                            EnginePacket::Message(SocketPayload::Binary(bytes.to_vec())),
+                        )
+                        .await
+                        .is_err()
+                        {
+                            break;
+                        }
+                    }
+                    Some(Ok(actix_ws::Message::Ping(bytes))) => {
+                        touch_session(&session).await;
+                        if ws_session.pong(&bytes).await.is_err() {
+                            break;
+                        }
+                    }
+                    Some(Ok(actix_ws::Message::Pong(_))) => {
+                        touch_session(&session).await;
+                    }
+                    Some(Ok(actix_ws::Message::Close(reason))) => {
+                        let _ = ws_session.close(reason).await;
+                        break;
+                    }
+                    Some(Ok(actix_ws::Message::Continuation(_))) => {}
+                    Some(Ok(actix_ws::Message::Nop)) => {}
+                    Some(Err(_)) | None => break,
+                }
+            }
+            () = session.notify.notified() => {
+                for packet in session.drain().await {
+                    if send_ws_packet(&mut ws_session, packet).await.is_err() {
+                        io.remove_session(&session, DisconnectReason::TransportClosed).await;
+                        return;
+                    }
+                }
+            }
+            _ = heartbeat.tick() => {
+                if session.last_pong.lock().await.elapsed()
+                    > io.config().ping_interval + io.config().ping_timeout
+                {
+                    io.remove_session(&session, DisconnectReason::PingTimeout).await;
+                    return;
+                }
+                if ws_session.text("2").await.is_err() {
+                    io.remove_session(&session, DisconnectReason::TransportClosed).await;
+                    return;
+                }
+            }
+        }
+    }
+
+    io.remove_session(&session, DisconnectReason::TransportClosed)
+        .await;
+}
+
+async fn touch_session(session: &Session) {
+    *session.last_pong.lock().await = std::time::Instant::now();
+}
+
+async fn send_ws_packet(
+    ws_session: &mut actix_ws::Session,
+    packet: EnginePacket,
+) -> std::result::Result<(), actix_ws::Closed> {
+    match packet {
+        EnginePacket::Message(SocketPayload::Binary(bytes)) => {
+            ws_session.binary(bytes).await
+        }
+        packet => ws_session.text(encode_engine_packet(&packet, false)).await,
+    }
+}
+
+async fn handle_engine_packet(
+    io: &SocketIo,
+    session: Arc<Session>,
+    packet: EnginePacket,
+) -> Result<(), Error> {
+    match packet {
+        EnginePacket::Ping(data) => {
+            session.enqueue(EnginePacket::Pong(data)).await;
+        }
+        EnginePacket::Pong(_) => {
+            *session.last_pong.lock().await = std::time::Instant::now();
+        }
+        EnginePacket::Message(payload) => {
+            io.handle_socket_payload(session, payload)
+                .await
+                .map_err(map_socket_error)?;
+        }
+        EnginePacket::Close => {
+            io.remove_session(&session, DisconnectReason::Client).await;
+        }
+        EnginePacket::Open(_) => {
+            tracing::warn!("client sent unexpected Open packet");
+        }
+        EnginePacket::Upgrade | EnginePacket::Noop => {}
+    }
+    Ok(())
+}
+
+fn validate_eio(query: &EngineQuery) -> Result<(), Error> {
+    match query.eio.as_deref() {
+        Some("4") => Ok(()),
+        _ => Err(ErrorBadRequest("unsupported EIO version")),
+    }
+}
+
+fn validate_sid(sid: &str) -> Result<(), Error> {
+    if sid.is_empty()
+        || sid.len() > 128
+        || !sid.bytes().all(|byte| byte.is_ascii_graphic())
+    {
+        return Err(ErrorBadRequest("invalid sid"));
+    }
+    Ok(())
+}
+
+fn text_response(body: String) -> HttpResponse {
+    HttpResponse::Ok()
+        .insert_header((header::CONTENT_TYPE, "text/plain; charset=UTF-8"))
+        .body(body)
+}
+
+fn map_socket_error(err: SocketIoError) -> Error {
+    match err {
+        SocketIoError::UnknownSession | SocketIoError::UnknownNamespace(_) => {
+            ErrorNotFound(err)
+        }
+        SocketIoError::InvalidPacket(_) => ErrorBadRequest(err),
+        _ => ErrorInternalServerError(err),
+    }
+}
diff --git a/lib/socketio/adapter.rs b/lib/socketio/adapter.rs
new file mode 100644
index 0000000..fb84c5a
--- /dev/null
+++ b/lib/socketio/adapter.rs
@@ -0,0 +1,201 @@
+use std::{
+    collections::{HashMap, HashSet},
+    sync::Arc,
+};
+
+use async_trait::async_trait;
+use tokio::sync::RwLock;
+
+use crate::{error::Result, packet::Packet};
+
+#[derive(Clone, Debug, Default, serde::Deserialize, serde::Serialize)]
+pub struct BroadcastOptions {
+    pub namespace: String,
+    pub rooms: HashSet<String>,
+    pub except: HashSet<String>,
+    pub skip_sid: Option<String>,
+}
+
+#[async_trait]
+pub trait Adapter: Send + Sync {
+    async fn add_socket(&self, namespace: &str, sid: &str) -> Result<()>;
+    async fn remove_socket(&self, namespace: &str, sid: &str) -> Result<()>;
+    async fn add_to_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()>;
+    async fn remove_from_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()>;
+    async fn sockets(
+        &self,
+        namespace: &str,
+        opts: &BroadcastOptions,
+    ) -> Result<Vec<String>>;
+    async fn publish(
+        &self,
+        packet: &Packet,
+        opts: &BroadcastOptions,
+    ) -> Result<()>;
+}
+
+#[derive(Default)]
+pub struct MemoryAdapter {
+    state: RwLock<HashMap<String, NamespaceRooms>>,
+}
+
+#[derive(Default)]
+struct NamespaceRooms {
+    sockets: HashSet<String>,
+    rooms: HashMap<String, HashSet<String>>,
+}
+
+impl MemoryAdapter {
+    pub fn new() -> Arc<Self> {
+        Arc::new(Self::default())
+    }
+}
+
+#[async_trait]
+impl Adapter for MemoryAdapter {
+    async fn add_socket(&self, namespace: &str, sid: &str) -> Result<()> {
+        let mut state = self.state.write().await;
+        state
+            .entry(namespace.to_owned())
+            .or_default()
+            .sockets
+            .insert(sid.to_owned());
+        Ok(())
+    }
+
+    async fn remove_socket(&self, namespace: &str, sid: &str) -> Result<()> {
+        let mut state = self.state.write().await;
+        if let Some(ns) = state.get_mut(namespace) {
+            ns.sockets.remove(sid);
+            ns.rooms.retain(|_, sockets| {
+                sockets.remove(sid);
+                !sockets.is_empty()
+            });
+        }
+        Ok(())
+    }
+
+    async fn add_to_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()> {
+        let mut state = self.state.write().await;
+        let ns = state.entry(namespace.to_owned()).or_default();
+        ns.sockets.insert(sid.to_owned());
+        ns.rooms
+            .entry(room.to_owned())
+            .or_default()
+            .insert(sid.to_owned());
+        Ok(())
+    }
+
+    async fn remove_from_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()> {
+        let mut state = self.state.write().await;
+        if let Some(ns) = state.get_mut(namespace)
+            && let Some(sockets) = ns.rooms.get_mut(room)
+        {
+            sockets.remove(sid);
+        }
+        Ok(())
+    }
+
+    async fn sockets(
+        &self,
+        namespace: &str,
+        opts: &BroadcastOptions,
+    ) -> Result<Vec<String>> {
+        let state = self.state.read().await;
+        let Some(ns) = state.get(namespace) else {
+            return Ok(Vec::new());
+        };
+
+        let mut selected: HashSet<String> = if opts.rooms.is_empty() {
+            ns.sockets.iter().cloned().collect()
+        } else {
+            opts.rooms
+                .iter()
+                .filter_map(|room| ns.rooms.get(room))
+                .flat_map(|sockets| sockets.iter().cloned())
+                .collect()
+        };
+
+        for room in &opts.except {
+            if let Some(excluded) = ns.rooms.get(room) {
+                for sid in excluded {
+                    selected.remove(sid);
+                }
+            }
+        }
+        if let Some(skip_sid) = &opts.skip_sid {
+            selected.remove(skip_sid);
+        }
+
+        Ok(selected.into_iter().collect())
+    }
+
+    async fn publish(
+        &self,
+        _packet: &Packet,
+        _opts: &BroadcastOptions,
+    ) -> Result<()> {
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn memory_adapter_filters_rooms_and_except() {
+        let adapter = MemoryAdapter::new();
+        adapter.add_socket("/", "s1").await.unwrap();
+        adapter.add_socket("/", "s2").await.unwrap();
+        adapter.add_socket("/", "s3").await.unwrap();
+        adapter.add_to_room("/", "s1", "room-a").await.unwrap();
+        adapter.add_to_room("/", "s2", "room-a").await.unwrap();
+        adapter.add_to_room("/", "s2", "muted").await.unwrap();
+
+        let opts = BroadcastOptions {
+            namespace: "/".to_owned(),
+            rooms: HashSet::from(["room-a".to_owned()]),
+            except: HashSet::from(["muted".to_owned()]),
+            skip_sid: None,
+        };
+
+        assert_eq!(adapter.sockets("/", &opts).await.unwrap(), vec!["s1"]);
+    }
+
+    #[tokio::test]
+    async fn memory_adapter_can_skip_sender() {
+        let adapter = MemoryAdapter::new();
+        adapter.add_socket("/", "s1").await.unwrap();
+        adapter.add_socket("/", "s2").await.unwrap();
+
+        let opts = BroadcastOptions {
+            namespace: "/".to_owned(),
+            skip_sid: Some("s1".to_owned()),
+            ..BroadcastOptions::default()
+        };
+        let sockets = adapter.sockets("/", &opts).await.unwrap();
+
+        assert_eq!(sockets, vec!["s2"]);
+    }
+}
diff --git a/lib/socketio/config.rs b/lib/socketio/config.rs
new file mode 100644
index 0000000..4aa8562
--- /dev/null
+++ b/lib/socketio/config.rs
@@ -0,0 +1,24 @@
+use std::time::Duration;
+
+#[derive(Clone, Debug)]
+pub struct SocketIoConfig {
+    pub path: String,
+    pub ping_interval: Duration,
+    pub ping_timeout: Duration,
+    pub connect_timeout: Duration,
+    pub ack_timeout: Duration,
+    pub max_payload: usize,
+}
+
+impl Default for SocketIoConfig {
+    fn default() -> Self {
+        Self {
+            path: "/socket.io/".to_owned(),
+            ping_interval: Duration::from_millis(25_000),
+            ping_timeout: Duration::from_millis(20_000),
+            connect_timeout: Duration::from_millis(45_000),
+            ack_timeout: Duration::from_secs(10),
+            max_payload: 1_000_000,
+        }
+    }
+}
diff --git a/lib/socketio/engine_packet.rs b/lib/socketio/engine_packet.rs
new file mode 100644
index 0000000..013d7d5
--- /dev/null
+++ b/lib/socketio/engine_packet.rs
@@ -0,0 +1,121 @@
+use base64::{Engine, engine::general_purpose::STANDARD};
+use serde_json::Value;
+
+use crate::error::{Result, SocketIoError};
+
+const RECORD_SEPARATOR: char = '\x1e';
+
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum EnginePacket {
+    Open(Value),
+    Close,
+    Ping(Option<String>),
+    Pong(Option<String>),
+    Message(SocketPayload),
+    Upgrade,
+    Noop,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub(crate) enum SocketPayload {
+    Text(String),
+    Binary(Vec<u8>),
+}
+
+pub(crate) fn encode_engine_payload(
+    packets: &[EnginePacket],
+    polling: bool,
+) -> String {
+    packets
+        .iter()
+        .map(|packet| encode_engine_packet(packet, polling))
+        .collect::<Vec<_>>()
+        .join(&RECORD_SEPARATOR.to_string())
+}
+
+pub(crate) fn decode_engine_payload(
+    payload: &str,
+) -> Result<Vec<EnginePacket>> {
+    payload
+        .split(RECORD_SEPARATOR)
+        .filter(|item| !item.is_empty())
+        .map(decode_engine_text_packet)
+        .collect()
+}
+
+pub(crate) fn encode_engine_packet(
+    packet: &EnginePacket,
+    _polling: bool,
+) -> String {
+    match packet {
+        EnginePacket::Open(data) => format!("0{data}"),
+        EnginePacket::Close => "1".to_owned(),
+        EnginePacket::Ping(data) => {
+            format!("2{}", data.as_deref().unwrap_or_default())
+        }
+        EnginePacket::Pong(data) => {
+            format!("3{}", data.as_deref().unwrap_or_default())
+        }
+        EnginePacket::Message(SocketPayload::Text(text)) => format!("4{text}"),
+        EnginePacket::Message(SocketPayload::Binary(bytes)) => {
+            format!("b{}", STANDARD.encode(bytes))
+        }
+        EnginePacket::Upgrade => "5".to_owned(),
+        EnginePacket::Noop => "6".to_owned(),
+    }
+}
+
+pub(crate) fn decode_engine_text_packet(input: &str) -> Result<EnginePacket> {
+    if let Some(encoded) = input.strip_prefix('b') {
+        return Ok(EnginePacket::Message(SocketPayload::Binary(
+            STANDARD.decode(encoded).map_err(|_| {
+                SocketIoError::InvalidPacket(
+                    "invalid base64 payload".to_owned(),
+                )
+            })?,
+        )));
+    }
+
+    let mut chars = input.chars();
+    let packet_type = chars.next().ok_or_else(|| {
+        SocketIoError::InvalidPacket("empty engine packet".to_owned())
+    })?;
+    let rest = chars.as_str();
+    match packet_type {
+        '0' => Ok(EnginePacket::Open(serde_json::from_str(rest)?)),
+        '1' => Ok(EnginePacket::Close),
+        '2' => Ok(EnginePacket::Ping(non_empty(rest))),
+        '3' => Ok(EnginePacket::Pong(non_empty(rest))),
+        '4' => Ok(EnginePacket::Message(SocketPayload::Text(rest.to_owned()))),
+        '5' => Ok(EnginePacket::Upgrade),
+        '6' => Ok(EnginePacket::Noop),
+        _ => Err(SocketIoError::InvalidPacket(format!(
+            "unknown engine packet type {packet_type}"
+        ))),
+    }
+}
+
+fn non_empty(value: &str) -> Option<String> {
+    if value.is_empty() {
+        None
+    } else {
+        Some(value.to_owned())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn polling_payload_uses_record_separator() {
+        let packets = vec![
+            EnginePacket::Message(SocketPayload::Text("40".to_owned())),
+            EnginePacket::Message(SocketPayload::Text(
+                "42[\"ready\",null]".to_owned(),
+            )),
+        ];
+        let encoded = encode_engine_payload(&packets, true);
+        assert_eq!(decode_engine_payload(&encoded).unwrap(), packets);
+    }
+}
diff --git a/lib/socketio/error.rs b/lib/socketio/error.rs
new file mode 100644
index 0000000..1d27a94
--- /dev/null
+++ b/lib/socketio/error.rs
@@ -0,0 +1,19 @@
+#[derive(Debug, thiserror::Error)]
+pub enum SocketIoError {
+    #[error("invalid packet: {0}")]
+    InvalidPacket(String),
+    #[error("unknown session")]
+    UnknownSession,
+    #[error("unknown namespace: {0}")]
+    UnknownNamespace(String),
+    #[error("ack timeout")]
+    AckTimeout,
+    #[error("serialization failed: {0}")]
+    Serialization(#[from] serde_json::Error),
+    #[error("redis failed: {0}")]
+    Redis(#[from] redis::RedisError),
+    #[error("adapter failed: {0}")]
+    Adapter(String),
+}
+
+pub type Result<T> = std::result::Result<T, SocketIoError>;
diff --git a/lib/socketio/lib.rs b/lib/socketio/lib.rs
new file mode 100644
index 0000000..d2f6f4e
--- /dev/null
+++ b/lib/socketio/lib.rs
@@ -0,0 +1,23 @@
+mod actix;
+mod adapter;
+mod config;
+mod engine_packet;
+mod error;
+mod namespace;
+mod nats;
+mod packet;
+mod redis;
+mod server;
+mod session;
+mod socket;
+
+pub use actix::{configure, configure_at};
+pub use adapter::{Adapter, BroadcastOptions, MemoryAdapter};
+pub use config::SocketIoConfig;
+pub use error::{Result, SocketIoError};
+pub use namespace::Broadcast;
+pub use nats::{NatsJetStreamAdapter, NatsJetStreamAdapterConfig};
+pub use packet::{EventPayload, Packet, PacketType};
+pub use redis::{RedisClusterAdapter, RedisClusterAdapterConfig};
+pub use server::{Namespace, SocketIo, SocketIoBuilder};
+pub use socket::{AckSender, DisconnectReason, Socket};
diff --git a/lib/socketio/namespace.rs b/lib/socketio/namespace.rs
new file mode 100644
index 0000000..c9e06e3
--- /dev/null
+++ b/lib/socketio/namespace.rs
@@ -0,0 +1,152 @@
+use std::{
+    collections::HashMap, collections::HashSet, future::Future, sync::Arc,
+};
+
+use serde::Serialize;
+use serde_json::Value;
+use tokio::sync::RwLock;
+
+use crate::{
+    adapter::{Adapter, BroadcastOptions},
+    config::SocketIoConfig,
+    error::Result,
+    packet::EventPayload,
+    server::{Inner, Namespace, NamespaceState, SocketIo, SocketIoBuilder},
+    socket::{DisconnectReason, Socket},
+};
+
+impl SocketIoBuilder {
+    pub fn config(mut self, config: SocketIoConfig) -> Self {
+        self.config = config;
+        self
+    }
+
+    pub fn adapter(mut self, adapter: Arc<dyn Adapter>) -> Self {
+        self.adapter = adapter;
+        self
+    }
+
+    pub fn build(self) -> SocketIo {
+        let mut namespaces = HashMap::new();
+        namespaces.insert("/".to_owned(), Arc::new(NamespaceState::default()));
+        SocketIo {
+            inner: Arc::new(Inner {
+                config: self.config,
+                sessions: RwLock::new(HashMap::new()),
+                namespaces: RwLock::new(namespaces),
+                adapter: self.adapter,
+                next_ack_id: std::sync::atomic::AtomicU64::new(1),
+            }),
+        }
+    }
+}
+
+impl Namespace {
+    pub async fn on_connect<F, Fut>(&self, handler: F)
+    where
+        F: Fn(Socket) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = ()> + Send + 'static,
+    {
+        let state = self.io.ensure_namespace(&self.name).await;
+        *state.connect_handler.write().await =
+            Some(Arc::new(move |socket| Box::pin(handler(socket))));
+    }
+
+    pub async fn on_disconnect<F, Fut>(&self, handler: F)
+    where
+        F: Fn(Socket, DisconnectReason) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = ()> + Send + 'static,
+    {
+        let state = self.io.ensure_namespace(&self.name).await;
+        *state.disconnect_handler.write().await =
+            Some(Arc::new(move |socket, reason| {
+                Box::pin(handler(socket, reason))
+            }));
+    }
+
+    pub async fn use_middleware<F, Fut>(&self, middleware: F)
+    where
+        F: Fn(Socket, Option<Value>) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<()>> + Send + 'static,
+    {
+        let state = self.io.ensure_namespace(&self.name).await;
+        state
+            .middleware
+            .write()
+            .await
+            .push(Arc::new(move |socket, auth| {
+                Box::pin(middleware(socket, auth))
+            }));
+    }
+
+    pub async fn on<F, Fut>(&self, event: impl Into<String>, handler: F)
+    where
+        F: Fn(Socket, EventPayload) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = ()> + Send + 'static,
+    {
+        let state = self.io.ensure_namespace(&self.name).await;
+        state.event_handlers.write().await.insert(
+            event.into(),
+            Arc::new(move |socket, payload| Box::pin(handler(socket, payload))),
+        );
+    }
+
+    pub async fn emit<T: Serialize>(&self, event: &str, data: T) -> Result<()> {
+        self.to_all().emit(event, data).await
+    }
+
+    pub fn to(&self, room: impl Into<String>) -> Broadcast {
+        let mut rooms = HashSet::new();
+        rooms.insert(room.into());
+        Broadcast {
+            io: self.io.clone(),
+            opts: BroadcastOptions {
+                namespace: self.name.clone(),
+                rooms,
+                ..BroadcastOptions::default()
+            },
+        }
+    }
+
+    pub fn to_all(&self) -> Broadcast {
+        Broadcast {
+            io: self.io.clone(),
+            opts: BroadcastOptions {
+                namespace: self.name.clone(),
+                ..BroadcastOptions::default()
+            },
+        }
+    }
+}
+
+pub struct Broadcast {
+    io: SocketIo,
+    opts: BroadcastOptions,
+}
+
+impl Broadcast {
+    pub fn to(mut self, room: impl Into<String>) -> Self {
+        self.opts.rooms.insert(room.into());
+        self
+    }
+
+    pub fn except(mut self, room: impl Into<String>) -> Self {
+        self.opts.except.insert(room.into());
+        self
+    }
+
+    pub async fn emit<T: Serialize>(self, event: &str, data: T) -> Result<()> {
+        self.io.broadcast_with_opts(self.opts, event, data).await
+    }
+}
+
+impl Default for NamespaceState {
+    fn default() -> Self {
+        Self {
+            connect_handler: RwLock::new(None),
+            disconnect_handler: RwLock::new(None),
+            event_handlers: RwLock::new(HashMap::new()),
+            middleware: RwLock::new(Vec::new()),
+        }
+    }
+}
diff --git a/lib/socketio/nats.rs b/lib/socketio/nats.rs
new file mode 100644
index 0000000..b262a85
--- /dev/null
+++ b/lib/socketio/nats.rs
@@ -0,0 +1,211 @@
+use std::{sync::Arc, time::Duration};
+
+use async_nats::jetstream;
+use async_trait::async_trait;
+use futures_util::StreamExt;
+use tracing::warn;
+
+use crate::{
+    adapter::{Adapter, BroadcastOptions, MemoryAdapter},
+    error::{Result, SocketIoError},
+    packet::Packet,
+    server::SocketIo,
+};
+
+#[derive(Clone, Debug)]
+pub struct NatsJetStreamAdapterConfig {
+    pub stream_name: String,
+    pub subject: String,
+    pub durable_name: String,
+    pub node_id: String,
+    pub max_age: Duration,
+    pub ack_wait: Duration,
+}
+
+impl Default for NatsJetStreamAdapterConfig {
+    fn default() -> Self {
+        Self {
+            stream_name: "SOCKETIO_ADAPTER".to_owned(),
+            subject: "socketio.adapter.broadcast".to_owned(),
+            durable_name: format!("socketio-adapter-{}", uuid::Uuid::new_v4()),
+            node_id: uuid::Uuid::new_v4().to_string(),
+            max_age: Duration::from_secs(60 * 60),
+            ack_wait: Duration::from_secs(30),
+        }
+    }
+}
+
+pub struct NatsJetStreamAdapter {
+    local: Arc<MemoryAdapter>,
+    jetstream: jetstream::Context,
+    config: NatsJetStreamAdapterConfig,
+}
+
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+struct NatsMessage {
+    origin: String,
+    packet: NatsPacket,
+    opts: BroadcastOptions,
+}
+
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+struct NatsPacket {
+    encoded: String,
+    attachments: Vec<Vec<u8>>,
+}
+
+impl NatsJetStreamAdapter {
+    pub fn new(
+        jetstream: jetstream::Context,
+        config: NatsJetStreamAdapterConfig,
+    ) -> Arc<Self> {
+        Arc::new(Self {
+            local: MemoryAdapter::new(),
+            jetstream,
+            config,
+        })
+    }
+
+    pub async fn attach(self: Arc<Self>, io: SocketIo) -> Result<()> {
+        let stream = self
+            .jetstream
+            .get_or_create_stream(jetstream::stream::Config {
+                name: self.config.stream_name.clone(),
+                subjects: vec![self.config.subject.clone()],
+                max_age: self.config.max_age,
+                ..Default::default()
+            })
+            .await
+            .map_err(|err| {
+                SocketIoError::Adapter(format!("nats stream failed: {err}"))
+            })?;
+
+        let consumer = stream
+            .get_or_create_consumer(
+                &self.config.durable_name,
+                jetstream::consumer::pull::Config {
+                    durable_name: Some(self.config.durable_name.clone()),
+                    filter_subject: self.config.subject.clone(),
+                    ack_wait: self.config.ack_wait,
+                    ..Default::default()
+                },
+            )
+            .await
+            .map_err(|err| {
+                SocketIoError::Adapter(format!("nats consumer failed: {err}"))
+            })?;
+
+        let node_id = self.config.node_id.clone();
+        actix_web::rt::spawn(async move {
+            let messages = consumer.messages().await;
+            let mut messages = match messages {
+                Ok(messages) => messages,
+                Err(err) => {
+                    warn!(error = %err, "failed to open nats jetstream adapter consumer");
+                    return;
+                }
+            };
+
+            while let Some(message) = messages.next().await {
+                let Ok(message) = message else {
+                    warn!("failed to receive nats jetstream adapter message");
+                    continue;
+                };
+                let payload = message.payload.to_vec();
+                let Ok(message_data) =
+                    serde_json::from_slice::<NatsMessage>(&payload)
+                else {
+                    warn!("failed to parse nats jetstream adapter message");
+                    let _ = message.ack().await;
+                    continue;
+                };
+                if message_data.origin == node_id {
+                    let _ = message.ack().await;
+                    continue;
+                }
+                let Ok(mut packet) =
+                    Packet::decode(&message_data.packet.encoded)
+                else {
+                    warn!(
+                        "failed to decode nats jetstream adapter socket.io packet"
+                    );
+                    let _ = message.ack().await;
+                    continue;
+                };
+                packet.attachments = message_data.packet.attachments;
+                if let Err(err) =
+                    io.deliver_remote_packet(message_data.opts, packet).await
+                {
+                    warn!(error = %err, "failed to deliver nats jetstream adapter packet");
+                }
+                let _ = message.ack().await;
+            }
+        });
+
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Adapter for NatsJetStreamAdapter {
+    async fn add_socket(&self, namespace: &str, sid: &str) -> Result<()> {
+        self.local.add_socket(namespace, sid).await
+    }
+
+    async fn remove_socket(&self, namespace: &str, sid: &str) -> Result<()> {
+        self.local.remove_socket(namespace, sid).await
+    }
+
+    async fn add_to_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()> {
+        self.local.add_to_room(namespace, sid, room).await
+    }
+
+    async fn remove_from_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()> {
+        self.local.remove_from_room(namespace, sid, room).await
+    }
+
+    async fn sockets(
+        &self,
+        namespace: &str,
+        opts: &BroadcastOptions,
+    ) -> Result<Vec<String>> {
+        self.local.sockets(namespace, opts).await
+    }
+
+    async fn publish(
+        &self,
+        packet: &Packet,
+        opts: &BroadcastOptions,
+    ) -> Result<()> {
+        let message = NatsMessage {
+            origin: self.config.node_id.clone(),
+            packet: NatsPacket {
+                encoded: packet.encode(),
+                attachments: packet.attachments.clone(),
+            },
+            opts: opts.clone(),
+        };
+        let payload = serde_json::to_vec(&message)?;
+        let ack = self
+            .jetstream
+            .publish(self.config.subject.clone(), payload.into())
+            .await
+            .map_err(|err| {
+                SocketIoError::Adapter(format!("nats publish failed: {err}"))
+            })?;
+        ack.await.map_err(|err| {
+            SocketIoError::Adapter(format!("nats publish ack failed: {err}"))
+        })?;
+        Ok(())
+    }
+}
diff --git a/lib/socketio/packet.rs b/lib/socketio/packet.rs
new file mode 100644
index 0000000..bf58dc8
--- /dev/null
+++ b/lib/socketio/packet.rs
@@ -0,0 +1,354 @@
+use serde_json::{Value, json};
+
+use crate::error::{Result, SocketIoError};
+
+#[derive(
+    Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize,
+)]
+pub enum PacketType {
+    Connect,
+    Disconnect,
+    Event,
+    Ack,
+    ConnectError,
+    BinaryEvent,
+    BinaryAck,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct Packet {
+    pub packet_type: PacketType,
+    pub namespace: String,
+    pub id: Option<u64>,
+    pub data: Option<Value>,
+    pub attachments: Vec<Vec<u8>>,
+    pub expected_attachments: usize,
+}
+
+#[derive(Clone, Debug)]
+pub struct EventPayload {
+    pub event: String,
+    pub args: Vec<Value>,
+    pub binary: Vec<Vec<u8>>,
+    pub ack_id: Option<u64>,
+    pub ack: Option<crate::socket::AckSender>,
+}
+
+impl Packet {
+    pub fn connect(namespace: impl Into<String>, data: Option<Value>) -> Self {
+        Self::new(PacketType::Connect, namespace, None, data)
+    }
+
+    pub fn event(
+        namespace: impl Into<String>,
+        event: &str,
+        args: Vec<Value>,
+    ) -> Self {
+        let mut data = Vec::with_capacity(args.len() + 1);
+        data.push(Value::String(event.to_owned()));
+        data.extend(args);
+        Self::new(PacketType::Event, namespace, None, Some(Value::Array(data)))
+    }
+
+    pub fn ack(
+        namespace: impl Into<String>,
+        id: u64,
+        args: Vec<Value>,
+    ) -> Self {
+        Self::new(
+            PacketType::Ack,
+            namespace,
+            Some(id),
+            Some(Value::Array(args)),
+        )
+    }
+
+    pub fn connect_error(
+        namespace: impl Into<String>,
+        message: impl Into<String>,
+    ) -> Self {
+        Self::new(
+            PacketType::ConnectError,
+            namespace,
+            None,
+            Some(json!({ "message": message.into() })),
+        )
+    }
+
+    pub fn new(
+        packet_type: PacketType,
+        namespace: impl Into<String>,
+        id: Option<u64>,
+        data: Option<Value>,
+    ) -> Self {
+        Self {
+            packet_type,
+            namespace: namespace.into(),
+            id,
+            data,
+            attachments: Vec::new(),
+            expected_attachments: 0,
+        }
+    }
+
+    pub fn with_binary(mut self, attachments: Vec<Vec<u8>>) -> Self {
+        self.expected_attachments = attachments.len();
+        if self.expected_attachments > 0
+            && let Some(Value::Array(values)) = &mut self.data
+        {
+            for num in 0..self.expected_attachments {
+                values.push(json!({ "_placeholder": true, "num": num }));
+            }
+        }
+        self.attachments = attachments;
+        self.packet_type = match self.packet_type {
+            PacketType::Ack => PacketType::BinaryAck,
+            PacketType::Event => PacketType::BinaryEvent,
+            other => other,
+        };
+        self
+    }
+
+    pub fn encode(&self) -> String {
+        let mut out = String::new();
+        out.push(packet_type_digit(self.packet_type));
+
+        if matches!(
+            self.packet_type,
+            PacketType::BinaryEvent | PacketType::BinaryAck
+        ) {
+            out.push_str(&self.expected_attachments.to_string());
+            out.push('-');
+        }
+
+        if self.namespace != "/" {
+            out.push_str(&self.namespace);
+            out.push(',');
+        }
+
+        if let Some(id) = self.id {
+            out.push_str(&id.to_string());
+        }
+
+        if let Some(data) = &self.data {
+            out.push_str(&data.to_string());
+        }
+
+        out
+    }
+
+    pub fn decode(input: &str) -> Result<Self> {
+        let mut chars = input.char_indices();
+        let (_, first) = chars.next().ok_or_else(|| {
+            SocketIoError::InvalidPacket("empty packet".to_owned())
+        })?;
+        let packet_type = packet_type_from_digit(first)?;
+        let mut index = first.len_utf8();
+        let mut expected_attachments = 0;
+
+        if matches!(
+            packet_type,
+            PacketType::BinaryEvent | PacketType::BinaryAck
+        ) {
+            let rest = &input[index..];
+            let dash = rest.find('-').ok_or_else(|| {
+                SocketIoError::InvalidPacket(
+                    "binary packet missing attachment count".to_owned(),
+                )
+            })?;
+            expected_attachments = rest[..dash].parse().map_err(|_| {
+                SocketIoError::InvalidPacket(
+                    "invalid attachment count".to_owned(),
+                )
+            })?;
+            index += dash + 1;
+        }
+
+        let namespace = if input[index..].starts_with('/') {
+            let rest = &input[index..];
+            if let Some(comma) = rest.find(',') {
+                index += comma + 1;
+                rest[..comma].to_owned()
+            } else {
+                index = input.len();
+                rest.to_owned()
+            }
+        } else {
+            "/".to_owned()
+        };
+
+        let id_start = index;
+        while let Some(ch) = input[index..].chars().next() {
+            if ch.is_ascii_digit() {
+                index += ch.len_utf8();
+            } else {
+                break;
+            }
+        }
+        let id = if index > id_start {
+            Some(input[id_start..index].parse().map_err(|_| {
+                SocketIoError::InvalidPacket(
+                    "invalid acknowledgment id".to_owned(),
+                )
+            })?)
+        } else {
+            None
+        };
+
+        let data = if index < input.len() {
+            Some(serde_json::from_str(&input[index..])?)
+        } else {
+            None
+        };
+
+        Ok(Self {
+            packet_type,
+            namespace,
+            id,
+            data,
+            attachments: Vec::new(),
+            expected_attachments,
+        })
+    }
+
+    pub(crate) fn into_event_payload(
+        self,
+        ack: Option<crate::socket::AckSender>,
+    ) -> Result<EventPayload> {
+        let values = match self.data {
+            Some(Value::Array(values)) if !values.is_empty() => values,
+            _ => {
+                return Err(SocketIoError::InvalidPacket(
+                    "event payload must be a non-empty array".to_owned(),
+                ));
+            }
+        };
+        let mut values = values.into_iter();
+        let event = values
+            .next()
+            .and_then(|value| value.as_str().map(ToOwned::to_owned))
+            .ok_or_else(|| {
+                SocketIoError::InvalidPacket(
+                    "event name must be a string".to_owned(),
+                )
+            })?;
+
+        let args = values.filter(|value| !is_placeholder(value)).collect();
+
+        Ok(EventPayload {
+            event,
+            args,
+            binary: self.attachments,
+            ack_id: self.id,
+            ack,
+        })
+    }
+}
+
+fn is_placeholder(value: &Value) -> bool {
+    value
+        .as_object()
+        .and_then(|object| object.get("_placeholder"))
+        .and_then(Value::as_bool)
+        .unwrap_or(false)
+}
+
+fn packet_type_digit(packet_type: PacketType) -> char {
+    match packet_type {
+        PacketType::Connect => '0',
+        PacketType::Disconnect => '1',
+        PacketType::Event => '2',
+        PacketType::Ack => '3',
+        PacketType::ConnectError => '4',
+        PacketType::BinaryEvent => '5',
+        PacketType::BinaryAck => '6',
+    }
+}
+
+fn packet_type_from_digit(value: char) -> Result<PacketType> {
+    match value {
+        '0' => Ok(PacketType::Connect),
+        '1' => Ok(PacketType::Disconnect),
+        '2' => Ok(PacketType::Event),
+        '3' => Ok(PacketType::Ack),
+        '4' => Ok(PacketType::ConnectError),
+        '5' => Ok(PacketType::BinaryEvent),
+        '6' => Ok(PacketType::BinaryAck),
+        _ => Err(SocketIoError::InvalidPacket(format!(
+            "unknown socket packet type {value}"
+        ))),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn event_packet_round_trips() {
+        let packet =
+            Packet::event("/", "message", vec![json!({ "body": "hello" })]);
+        assert_eq!(packet.encode(), "2[\"message\",{\"body\":\"hello\"}]");
+
+        let decoded = Packet::decode(&packet.encode()).unwrap();
+        assert_eq!(decoded.packet_type, PacketType::Event);
+        assert_eq!(decoded.namespace, "/");
+        assert_eq!(decoded.data, packet.data);
+    }
+
+    #[test]
+    fn event_packet_accepts_namespace_and_ack_id() {
+        let decoded =
+            Packet::decode("2/admin,17[\"save\",{\"ok\":true}]").unwrap();
+        assert_eq!(decoded.packet_type, PacketType::Event);
+        assert_eq!(decoded.namespace, "/admin");
+        assert_eq!(decoded.id, Some(17));
+    }
+
+    #[test]
+    fn binary_packet_accepts_attachment_count() {
+        let decoded = Packet::decode(
+            "51-/admin,13[\"file\",{\"_placeholder\":true,\"num\":0}]",
+        )
+        .unwrap();
+        assert_eq!(decoded.packet_type, PacketType::BinaryEvent);
+        assert_eq!(decoded.expected_attachments, 1);
+        assert_eq!(decoded.namespace, "/admin");
+        assert_eq!(decoded.id, Some(13));
+    }
+
+    #[test]
+    fn binary_emit_adds_placeholders() {
+        let packet = Packet::event("/", "file", vec![json!("meta")])
+            .with_binary(vec![vec![1, 2]]);
+        assert_eq!(
+            packet.encode(),
+            "51-[\"file\",\"meta\",{\"_placeholder\":true,\"num\":0}]"
+        );
+    }
+
+    #[test]
+    fn decode_empty_packet_returns_error() {
+        assert!(Packet::decode("").is_err());
+    }
+
+    #[test]
+    fn decode_unknown_type_returns_error() {
+        assert!(Packet::decode("9[]").is_err());
+    }
+
+    #[test]
+    fn default_namespace_omits_prefix_in_encode() {
+        let packet = Packet::event("/", "ping", vec![]);
+        assert_eq!(packet.encode(), "2[\"ping\"]");
+    }
+
+    #[test]
+    fn custom_namespace_includes_trailing_comma() {
+        let packet = Packet::event("/chat", "msg", vec![json!("hi")]);
+        let encoded = packet.encode();
+        assert!(encoded.starts_with("2/chat,"));
+        let decoded = Packet::decode(&encoded).unwrap();
+        assert_eq!(decoded.namespace, "/chat");
+    }
+}
diff --git a/lib/socketio/redis.rs b/lib/socketio/redis.rs
new file mode 100644
index 0000000..dad2bbe
--- /dev/null
+++ b/lib/socketio/redis.rs
@@ -0,0 +1,177 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use redis::{AsyncCommands, Msg, PushInfo};
+use tracing::warn;
+
+use crate::{
+    adapter::{Adapter, BroadcastOptions, MemoryAdapter},
+    error::Result,
+    packet::Packet,
+    server::SocketIo,
+};
+
+#[derive(Clone, Debug)]
+pub struct RedisClusterAdapterConfig {
+    pub channel_prefix: String,
+    pub node_id: String,
+}
+
+impl Default for RedisClusterAdapterConfig {
+    fn default() -> Self {
+        Self {
+            channel_prefix: "socket.io:{adapter}".to_owned(),
+            node_id: uuid::Uuid::new_v4().to_string(),
+        }
+    }
+}
+
+pub struct RedisClusterAdapter {
+    local: Arc<MemoryAdapter>,
+    pool: deadpool_redis::cluster::Pool,
+    config: RedisClusterAdapterConfig,
+}
+
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+struct RedisMessage {
+    origin: String,
+    packet: RedisPacket,
+    opts: BroadcastOptions,
+}
+
+#[derive(Debug, serde::Deserialize, serde::Serialize)]
+struct RedisPacket {
+    encoded: String,
+    attachments: Vec<Vec<u8>>,
+}
+
+impl RedisClusterAdapter {
+    pub fn new(
+        pool: deadpool_redis::cluster::Pool,
+        config: RedisClusterAdapterConfig,
+    ) -> Arc<Self> {
+        Arc::new(Self {
+            local: MemoryAdapter::new(),
+            pool,
+            config,
+        })
+    }
+
+    pub async fn attach_with_push_receiver(
+        self: Arc<Self>,
+        io: SocketIo,
+        mut rx: tokio::sync::mpsc::UnboundedReceiver<PushInfo>,
+    ) -> Result<()> {
+        let channel = self.channel();
+        let mut conn = self.pool.get().await.map_err(|err| {
+            redis::RedisError::from((
+                redis::ErrorKind::Io,
+                "redis pool failed",
+                err.to_string(),
+            ))
+        })?;
+        let _: () = conn.subscribe(&channel).await?;
+        let node_id = self.config.node_id.clone();
+
+        actix_web::rt::spawn(async move {
+            let mut _subscribed_conn = conn;
+            while let Some(push) = rx.recv().await {
+                let Some(message) = Msg::from_push_info(push) else {
+                    continue;
+                };
+                let Ok(payload) = message.get_payload::<String>() else {
+                    warn!("failed to decode redis adapter payload");
+                    continue;
+                };
+                let Ok(message) =
+                    serde_json::from_str::<RedisMessage>(&payload)
+                else {
+                    warn!("failed to parse redis adapter message");
+                    continue;
+                };
+                if message.origin == node_id {
+                    continue;
+                }
+                let Ok(mut packet) = Packet::decode(&message.packet.encoded)
+                else {
+                    warn!("failed to decode redis adapter socket.io packet");
+                    continue;
+                };
+                packet.attachments = message.packet.attachments;
+                if let Err(err) =
+                    io.deliver_remote_packet(message.opts, packet).await
+                {
+                    warn!(error = %err, "failed to deliver redis adapter packet");
+                }
+            }
+        });
+
+        Ok(())
+    }
+
+    fn channel(&self) -> String {
+        format!("{}:broadcast", self.config.channel_prefix)
+    }
+}
+
+#[async_trait]
+impl Adapter for RedisClusterAdapter {
+    async fn add_socket(&self, namespace: &str, sid: &str) -> Result<()> {
+        self.local.add_socket(namespace, sid).await
+    }
+
+    async fn remove_socket(&self, namespace: &str, sid: &str) -> Result<()> {
+        self.local.remove_socket(namespace, sid).await
+    }
+
+    async fn add_to_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()> {
+        self.local.add_to_room(namespace, sid, room).await
+    }
+
+    async fn remove_from_room(
+        &self,
+        namespace: &str,
+        sid: &str,
+        room: &str,
+    ) -> Result<()> {
+        self.local.remove_from_room(namespace, sid, room).await
+    }
+
+    async fn sockets(
+        &self,
+        namespace: &str,
+        opts: &BroadcastOptions,
+    ) -> Result<Vec<String>> {
+        self.local.sockets(namespace, opts).await
+    }
+
+    async fn publish(
+        &self,
+        packet: &Packet,
+        opts: &BroadcastOptions,
+    ) -> Result<()> {
+        let message = RedisMessage {
+            origin: self.config.node_id.clone(),
+            packet: RedisPacket {
+                encoded: packet.encode(),
+                attachments: packet.attachments.clone(),
+            },
+            opts: opts.clone(),
+        };
+        let payload = serde_json::to_string(&message)?;
+        let mut conn = self.pool.get().await.map_err(|err| {
+            redis::RedisError::from((
+                redis::ErrorKind::Io,
+                "redis pool failed",
+                err.to_string(),
+            ))
+        })?;
+        let _: usize = conn.publish(self.channel(), payload).await?;
+        Ok(())
+    }
+}
diff --git a/lib/socketio/server.rs b/lib/socketio/server.rs
new file mode 100644
index 0000000..6d3b913
--- /dev/null
+++ b/lib/socketio/server.rs
@@ -0,0 +1,625 @@
+use std::{
+    collections::{HashMap, HashSet},
+    future::Future,
+    pin::Pin,
+    sync::{
+        Arc,
+        atomic::{AtomicU64, Ordering},
+    },
+};
+
+use serde::Serialize;
+use serde_json::{Value, json};
+use tokio::sync::RwLock;
+
+use crate::{
+    adapter::{Adapter, BroadcastOptions, MemoryAdapter},
+    config::SocketIoConfig,
+    engine_packet::SocketPayload,
+    error::{Result, SocketIoError},
+    packet::{EventPayload, Packet, PacketType},
+    session::{PendingBinary, Session, SocketState},
+    socket::{AckSender, DisconnectReason, Socket},
+};
+
+pub(crate) type BoxFuture = Pin<Box<dyn Future<Output = ()> + Send>>;
+pub(crate) type ConnectHandler = Arc<dyn Fn(Socket) -> BoxFuture + Send + Sync>;
+pub(crate) type DisconnectHandler =
+    Arc<dyn Fn(Socket, DisconnectReason) -> BoxFuture + Send + Sync>;
+pub(crate) type EventHandler =
+    Arc<dyn Fn(Socket, EventPayload) -> BoxFuture + Send + Sync>;
+pub(crate) type Middleware = Arc<
+    dyn Fn(
+            Socket,
+            Option<Value>,
+        ) -> Pin<Box<dyn Future<Output = Result<()>> + Send>>
+        + Send
+        + Sync,
+>;
+
+#[derive(Clone)]
+pub struct SocketIo {
+    pub(crate) inner: Arc<Inner>,
+}
+
+#[derive(Clone)]
+pub struct Namespace {
+    pub(crate) io: SocketIo,
+    pub(crate) name: String,
+}
+
+pub struct SocketIoBuilder {
+    pub(crate) config: SocketIoConfig,
+    pub(crate) adapter: Arc<dyn Adapter>,
+}
+
+pub(crate) struct Inner {
+    pub(crate) config: SocketIoConfig,
+    pub(crate) sessions: RwLock<HashMap<String, Arc<Session>>>,
+    pub(crate) namespaces: RwLock<HashMap<String, Arc<NamespaceState>>>,
+    pub(crate) adapter: Arc<dyn Adapter>,
+    pub(crate) next_ack_id: AtomicU64,
+}
+
+pub(crate) struct NamespaceState {
+    pub(crate) connect_handler: RwLock<Option<ConnectHandler>>,
+    pub(crate) disconnect_handler: RwLock<Option<DisconnectHandler>>,
+    pub(crate) event_handlers: RwLock<HashMap<String, EventHandler>>,
+    pub(crate) middleware: RwLock<Vec<Middleware>>,
+}
+
+impl Default for SocketIo {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SocketIo {
+    pub fn builder() -> SocketIoBuilder {
+        SocketIoBuilder {
+            config: SocketIoConfig::default(),
+            adapter: MemoryAdapter::new(),
+        }
+    }
+
+    pub fn new() -> Self {
+        Self::builder().build()
+    }
+
+    pub fn config(&self) -> &SocketIoConfig {
+        &self.inner.config
+    }
+
+    pub async fn namespace(&self, name: impl Into<String>) -> Namespace {
+        let name = normalize_namespace(name.into());
+        self.ensure_namespace(&name).await;
+        Namespace {
+            io: self.clone(),
+            name,
+        }
+    }
+
+    pub async fn on_connect<F, Fut>(&self, handler: F)
+    where
+        F: Fn(Socket) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = ()> + Send + 'static,
+    {
+        self.namespace("/").await.on_connect(handler).await;
+    }
+
+    pub async fn on_disconnect<F, Fut>(&self, handler: F)
+    where
+        F: Fn(Socket, DisconnectReason) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = ()> + Send + 'static,
+    {
+        self.namespace("/").await.on_disconnect(handler).await;
+    }
+
+    pub async fn on<F, Fut>(&self, event: impl Into<String>, handler: F)
+    where
+        F: Fn(Socket, EventPayload) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = ()> + Send + 'static,
+    {
+        self.namespace("/").await.on(event, handler).await;
+    }
+
+    pub async fn emit<T: Serialize>(&self, event: &str, data: T) -> Result<()> {
+        self.namespace("/").await.emit(event, data).await
+    }
+
+    pub async fn emit_to_room<T: Serialize>(
+        &self,
+        room: &str,
+        event: &str,
+        data: T,
+    ) -> Result<()> {
+        self.namespace("/")
+            .await
+            .to(room.to_owned())
+            .emit(event, data)
+            .await
+    }
+
+    pub(crate) async fn session(&self, sid: &str) -> Option<Arc<Session>> {
+        self.inner.sessions.read().await.get(sid).cloned()
+    }
+
+    pub(crate) async fn insert_session(&self, session: Arc<Session>) {
+        self.inner
+            .sessions
+            .write()
+            .await
+            .insert(session.engine_id.clone(), session);
+    }
+
+    pub(crate) async fn remove_session(
+        &self,
+        session: &Arc<Session>,
+        reason: DisconnectReason,
+    ) {
+        self.inner.sessions.write().await.remove(&session.engine_id);
+        let namespaces = session
+            .namespaces
+            .lock()
+            .await
+            .keys()
+            .cloned()
+            .collect::<Vec<_>>();
+        for namespace in namespaces {
+            let _ = self
+                .disconnect_socket(&namespace, session, reason.clone())
+                .await;
+        }
+    }
+
+    pub(crate) async fn handle_socket_payload(
+        &self,
+        session: Arc<Session>,
+        payload: SocketPayload,
+    ) -> Result<()> {
+        match payload {
+            SocketPayload::Text(text) => {
+                let packet = Packet::decode(&text)?;
+                if packet.expected_attachments == 0 {
+                    self.handle_socket_packet(session, packet).await
+                } else {
+                    *session.pending_binary.lock().await =
+                        Some(PendingBinary { packet });
+                    Ok(())
+                }
+            }
+            SocketPayload::Binary(bytes) => {
+                let mut pending = session.pending_binary.lock().await;
+                let Some(mut pending_binary) = pending.take() else {
+                    return Err(SocketIoError::InvalidPacket(
+                        "unexpected binary attachment".to_owned(),
+                    ));
+                };
+                pending_binary.packet.attachments.push(bytes);
+                if pending_binary.packet.attachments.len()
+                    == pending_binary.packet.expected_attachments
+                {
+                    drop(pending);
+                    self.handle_socket_packet(session, pending_binary.packet)
+                        .await
+                } else {
+                    *pending = Some(pending_binary);
+                    Ok(())
+                }
+            }
+        }
+    }
+
+    async fn handle_socket_packet(
+        &self,
+        session: Arc<Session>,
+        packet: Packet,
+    ) -> Result<()> {
+        match packet.packet_type {
+            PacketType::Connect => {
+                self.connect_namespace(session, packet).await
+            }
+            PacketType::Disconnect => {
+                self.disconnect_socket(
+                    &packet.namespace,
+                    &session,
+                    DisconnectReason::Client,
+                )
+                .await
+            }
+            PacketType::Event | PacketType::BinaryEvent => {
+                self.dispatch_event(session, packet).await
+            }
+            PacketType::Ack | PacketType::BinaryAck => {
+                self.resolve_ack(session, packet).await
+            }
+            PacketType::ConnectError => Ok(()),
+        }
+    }
+
+    async fn connect_namespace(
+        &self,
+        session: Arc<Session>,
+        packet: Packet,
+    ) -> Result<()> {
+        let namespace = normalize_namespace(packet.namespace);
+        let state = self.namespace_state(&namespace).await?;
+        let sid = uuid::Uuid::new_v4().to_string();
+        let socket = Socket {
+            io: self.clone(),
+            session: session.clone(),
+            namespace: namespace.clone(),
+            sid: sid.clone(),
+        };
+
+        for middleware in state.middleware.read().await.iter().cloned() {
+            if let Err(err) =
+                middleware(socket.clone(), packet.data.clone()).await
+            {
+                session
+                    .enqueue_socket_packet(Packet::connect_error(
+                        &namespace,
+                        err.to_string(),
+                    ))
+                    .await;
+                return Ok(());
+            }
+        }
+
+        self.inner
+            .adapter
+            .add_socket(&namespace, &session.engine_id)
+            .await?;
+        session.namespaces.lock().await.insert(
+            namespace.clone(),
+            SocketState {
+                sid,
+                rooms: HashSet::new(),
+                auth: packet.data,
+            },
+        );
+        session
+            .enqueue_socket_packet(Packet::connect(
+                &namespace,
+                Some(json!({ "sid": socket.sid })),
+            ))
+            .await;
+
+        if let Some(handler) = state.connect_handler.read().await.clone() {
+            handler(socket).await;
+        }
+        Ok(())
+    }
+
+    pub(crate) async fn disconnect_socket(
+        &self,
+        namespace: &str,
+        session: &Arc<Session>,
+        reason: DisconnectReason,
+    ) -> Result<()> {
+        let namespace = normalize_namespace(namespace.to_owned());
+        let removed = session.namespaces.lock().await.remove(&namespace);
+        if let Some(socket_state) = removed {
+            self.inner
+                .adapter
+                .remove_socket(&namespace, &session.engine_id)
+                .await?;
+            if let Ok(state) = self.namespace_state(&namespace).await
+                && let Some(handler) =
+                    state.disconnect_handler.read().await.clone()
+            {
+                handler(
+                    Socket {
+                        io: self.clone(),
+                        session: session.clone(),
+                        namespace,
+                        sid: socket_state.sid,
+                    },
+                    reason,
+                )
+                .await;
+            }
+        }
+        Ok(())
+    }
+
+    async fn dispatch_event(
+        &self,
+        session: Arc<Session>,
+        packet: Packet,
+    ) -> Result<()> {
+        let namespace = normalize_namespace(packet.namespace.clone());
+        let state = self.namespace_state(&namespace).await?;
+        let socket_state = session
+            .namespaces
+            .lock()
+            .await
+            .get(&namespace)
+            .map(|state| state.sid.clone())
+            .ok_or_else(|| {
+                SocketIoError::UnknownNamespace(namespace.clone())
+            })?;
+        let ack = packet
+            .id
+            .map(|id| AckSender::new(session.clone(), namespace.clone(), id));
+        let payload = packet.into_event_payload(ack)?;
+        let handler = state
+            .event_handlers
+            .read()
+            .await
+            .get(&payload.event)
+            .cloned();
+        if let Some(handler) = handler {
+            handler(
+                Socket {
+                    io: self.clone(),
+                    session,
+                    namespace,
+                    sid: socket_state,
+                },
+                payload,
+            )
+            .await;
+        }
+        Ok(())
+    }
+
+    async fn resolve_ack(
+        &self,
+        session: Arc<Session>,
+        packet: Packet,
+    ) -> Result<()> {
+        let Some(id) = packet.id else {
+            return Ok(());
+        };
+        let args = match packet.data {
+            Some(Value::Array(values)) => values,
+            Some(value) => vec![value],
+            None => Vec::new(),
+        };
+        if let Some(sender) = session
+            .ack_waiters
+            .lock()
+            .await
+            .remove(&(normalize_namespace(packet.namespace), id))
+        {
+            let _ = sender.send(args);
+        }
+        Ok(())
+    }
+
+    pub(crate) async fn join(
+        &self,
+        namespace: &str,
+        engine_id: &str,
+        room: String,
+    ) -> Result<()> {
+        let namespace = normalize_namespace(namespace.to_owned());
+        let session = self
+            .session(engine_id)
+            .await
+            .ok_or(SocketIoError::UnknownSession)?;
+        if let Some(state) = session.namespaces.lock().await.get_mut(&namespace)
+        {
+            state.rooms.insert(room.clone());
+        }
+        self.inner
+            .adapter
+            .add_to_room(&namespace, engine_id, &room)
+            .await
+    }
+
+    pub(crate) async fn leave(
+        &self,
+        namespace: &str,
+        engine_id: &str,
+        room: &str,
+    ) -> Result<()> {
+        let namespace = normalize_namespace(namespace.to_owned());
+        let session = self
+            .session(engine_id)
+            .await
+            .ok_or(SocketIoError::UnknownSession)?;
+        if let Some(state) = session.namespaces.lock().await.get_mut(&namespace)
+        {
+            state.rooms.remove(room);
+        }
+        self.inner
+            .adapter
+            .remove_from_room(&namespace, engine_id, room)
+            .await
+    }
+
+    pub(crate) async fn emit_to_sid<T: Serialize>(
+        &self,
+        namespace: &str,
+        engine_id: &str,
+        event: &str,
+        data: T,
+    ) -> Result<()> {
+        let args = value_to_args(serde_json::to_value(data)?);
+        self.emit_packet_to_sid(
+            engine_id,
+            Packet::event(namespace, event, args),
+        )
+        .await
+    }
+
+    pub(crate) async fn emit_binary_to_sid(
+        &self,
+        namespace: &str,
+        engine_id: &str,
+        event: &str,
+        args: Vec<Value>,
+        binary: Vec<Vec<u8>>,
+    ) -> Result<()> {
+        self.emit_packet_to_sid(
+            engine_id,
+            Packet::event(namespace, event, args).with_binary(binary),
+        )
+        .await
+    }
+
+    pub(crate) async fn emit_to_sid_with_ack<T: Serialize>(
+        &self,
+        namespace: &str,
+        engine_id: &str,
+        event: &str,
+        data: T,
+    ) -> Result<Vec<Value>> {
+        let session = self
+            .session(engine_id)
+            .await
+            .ok_or(SocketIoError::UnknownSession)?;
+        let id = self.inner.next_ack_id.fetch_add(1, Ordering::Relaxed);
+        let (tx, rx) = tokio::sync::oneshot::channel();
+        session
+            .ack_waiters
+            .lock()
+            .await
+            .insert((normalize_namespace(namespace.to_owned()), id), tx);
+        let mut packet = Packet::event(
+            namespace,
+            event,
+            value_to_args(serde_json::to_value(data)?),
+        );
+        packet.id = Some(id);
+        session.enqueue_socket_packet(packet).await;
+
+        match tokio::time::timeout(self.inner.config.ack_timeout, rx).await {
+            Ok(Ok(values)) => Ok(values),
+            _ => {
+                session
+                    .ack_waiters
+                    .lock()
+                    .await
+                    .remove(&(normalize_namespace(namespace.to_owned()), id));
+                Err(SocketIoError::AckTimeout)
+            }
+        }
+    }
+
+    pub(crate) async fn broadcast_with_opts<T: Serialize>(
+        &self,
+        mut opts: BroadcastOptions,
+        event: &str,
+        data: T,
+    ) -> Result<()> {
+        opts.namespace = normalize_namespace(opts.namespace);
+        let packet = Packet::event(
+            &opts.namespace,
+            event,
+            value_to_args(serde_json::to_value(data)?),
+        );
+        self.broadcast_packet(opts, packet).await
+    }
+
+    async fn broadcast_packet(
+        &self,
+        opts: BroadcastOptions,
+        packet: Packet,
+    ) -> Result<()> {
+        let sockets =
+            self.inner.adapter.sockets(&opts.namespace, &opts).await?;
+        let mut failures = Vec::new();
+        for engine_id in sockets {
+            if let Err(err) =
+                self.emit_packet_to_sid(&engine_id, packet.clone()).await
+            {
+                failures.push(format!("{engine_id}: {err}"));
+            }
+        }
+        if let Err(err) = self.inner.adapter.publish(&packet, &opts).await {
+            failures.push(format!("adapter publish: {err}"));
+        }
+        if failures.is_empty() {
+            Ok(())
+        } else {
+            Err(SocketIoError::Adapter(format!(
+                "broadcast partially failed: {}",
+                failures.join("; ")
+            )))
+        }
+    }
+
+    pub(crate) async fn deliver_remote_packet(
+        &self,
+        opts: BroadcastOptions,
+        packet: Packet,
+    ) -> Result<()> {
+        let sockets =
+            self.inner.adapter.sockets(&opts.namespace, &opts).await?;
+        let mut failures = Vec::new();
+        for engine_id in sockets {
+            if let Err(err) =
+                self.emit_packet_to_sid(&engine_id, packet.clone()).await
+            {
+                failures.push(format!("{engine_id}: {err}"));
+            }
+        }
+        if failures.is_empty() {
+            Ok(())
+        } else {
+            Err(SocketIoError::Adapter(format!(
+                "remote broadcast partially failed: {}",
+                failures.join("; ")
+            )))
+        }
+    }
+
+    async fn emit_packet_to_sid(
+        &self,
+        engine_id: &str,
+        packet: Packet,
+    ) -> Result<()> {
+        let session = self
+            .session(engine_id)
+            .await
+            .ok_or(SocketIoError::UnknownSession)?;
+        session.enqueue_socket_packet(packet).await;
+        Ok(())
+    }
+
+    pub(crate) async fn ensure_namespace(
+        &self,
+        namespace: &str,
+    ) -> Arc<NamespaceState> {
+        let mut namespaces = self.inner.namespaces.write().await;
+        namespaces
+            .entry(namespace.to_owned())
+            .or_insert_with(|| Arc::new(NamespaceState::default()))
+            .clone()
+    }
+
+    async fn namespace_state(
+        &self,
+        namespace: &str,
+    ) -> Result<Arc<NamespaceState>> {
+        self.inner
+            .namespaces
+            .read()
+            .await
+            .get(namespace)
+            .cloned()
+            .ok_or_else(|| {
+                SocketIoError::UnknownNamespace(namespace.to_owned())
+            })
+    }
+}
+
+fn value_to_args(value: Value) -> Vec<Value> {
+    match value {
+        Value::Array(values) => values,
+        value => vec![value],
+    }
+}
+
+fn normalize_namespace(namespace: String) -> String {
+    if namespace.is_empty() || namespace == "/" {
+        "/".to_owned()
+    } else if namespace.starts_with('/') {
+        namespace
+    } else {
+        format!("/{namespace}")
+    }
+}
diff --git a/lib/socketio/session.rs b/lib/socketio/session.rs
new file mode 100644
index 0000000..707f2ba
--- /dev/null
+++ b/lib/socketio/session.rs
@@ -0,0 +1,90 @@
+use std::{
+    collections::{HashMap, HashSet, VecDeque},
+    sync::Arc,
+    sync::Mutex as StdMutex,
+    sync::atomic::AtomicBool,
+    time::Instant,
+};
+
+use serde_json::Value;
+use tokio::sync::{Mutex, Notify, oneshot};
+use uuid::Uuid;
+
+use crate::{
+    engine_packet::{EnginePacket, SocketPayload},
+    packet::Packet,
+};
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum Transport {
+    Polling,
+    WebSocket,
+}
+
+#[derive(Debug)]
+pub(crate) struct SocketState {
+    pub(crate) sid: String,
+    pub(crate) rooms: HashSet<String>,
+    pub(crate) auth: Option<Value>,
+}
+
+pub(crate) struct PendingBinary {
+    pub(crate) packet: Packet,
+}
+
+pub(crate) struct Session {
+    pub(crate) engine_id: String,
+    pub(crate) user: StdMutex<Option<Uuid>>,
+    pub(crate) transport: Mutex<Transport>,
+    pub(crate) namespaces: Mutex<HashMap<String, SocketState>>,
+    pub(crate) pending_binary: Mutex<Option<PendingBinary>>,
+    pub(crate) ack_waiters: Mutex<AckWaiters>,
+    pub(crate) last_pong: Mutex<Instant>,
+    queue: Mutex<VecDeque<EnginePacket>>,
+    pub(crate) get_active: Arc<AtomicBool>,
+    pub(crate) post_active: Arc<AtomicBool>,
+    pub(crate) notify: Notify,
+}
+
+pub(crate) type AckWaiters =
+    HashMap<(String, u64), oneshot::Sender<Vec<Value>>>;
+
+impl Session {
+    pub(crate) fn new(user: Option<Uuid>) -> Arc<Self> {
+        Arc::new(Self {
+            engine_id: Uuid::new_v4().to_string(),
+            user: StdMutex::new(user),
+            transport: Mutex::new(Transport::Polling),
+            namespaces: Mutex::new(HashMap::new()),
+            pending_binary: Mutex::new(None),
+            ack_waiters: Mutex::new(HashMap::new()),
+            last_pong: Mutex::new(Instant::now()),
+            queue: Mutex::new(VecDeque::new()),
+            get_active: Arc::new(AtomicBool::new(false)),
+            post_active: Arc::new(AtomicBool::new(false)),
+            notify: Notify::new(),
+        })
+    }
+
+    pub(crate) async fn enqueue(&self, packet: EnginePacket) {
+        self.queue.lock().await.push_back(packet);
+        self.notify.notify_waiters();
+    }
+
+    pub(crate) async fn enqueue_socket_packet(&self, packet: Packet) {
+        self.enqueue(EnginePacket::Message(SocketPayload::Text(
+            packet.encode(),
+        )))
+        .await;
+        for attachment in packet.attachments {
+            self.enqueue(EnginePacket::Message(SocketPayload::Binary(
+                attachment,
+            )))
+            .await;
+        }
+    }
+
+    pub(crate) async fn drain(&self) -> Vec<EnginePacket> {
+        self.queue.lock().await.drain(..).collect()
+    }
+}
diff --git a/lib/socketio/socket.rs b/lib/socketio/socket.rs
new file mode 100644
index 0000000..5e57be1
--- /dev/null
+++ b/lib/socketio/socket.rs
@@ -0,0 +1,185 @@
+use std::fmt;
+use std::{collections::HashSet, sync::Arc};
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::{
+    adapter::BroadcastOptions, error::Result, packet::Packet, server::SocketIo,
+    session::Session,
+};
+
+#[derive(Clone)]
+pub struct Socket {
+    pub(crate) io: SocketIo,
+    pub(crate) session: Arc<Session>,
+    pub(crate) namespace: String,
+    pub(crate) sid: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum DisconnectReason {
+    Client,
+    TransportClosed,
+    PingTimeout,
+    Server,
+}
+
+#[derive(Clone)]
+pub struct AckSender {
+    session: Arc<Session>,
+    namespace: String,
+    id: u64,
+}
+
+impl fmt::Debug for AckSender {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("AckSender")
+            .field("namespace", &self.namespace)
+            .field("id", &self.id)
+            .finish_non_exhaustive()
+    }
+}
+
+impl AckSender {
+    pub(crate) fn new(
+        session: Arc<Session>,
+        namespace: String,
+        id: u64,
+    ) -> Self {
+        Self {
+            session,
+            namespace,
+            id,
+        }
+    }
+
+    pub async fn send<T: Serialize>(&self, data: T) -> Result<()> {
+        let args = match serde_json::to_value(data)? {
+            Value::Array(values) => values,
+            value => vec![value],
+        };
+        self.session
+            .enqueue_socket_packet(Packet::ack(&self.namespace, self.id, args))
+            .await;
+        Ok(())
+    }
+}
+
+impl Socket {
+    pub fn id(&self) -> &str {
+        &self.sid
+    }
+
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+
+    pub fn session_user(&self) -> Option<uuid::Uuid> {
+        self.session.user.lock().unwrap_or_else(|e| e.into_inner()).clone()
+    }
+
+    pub fn set_user(&self, user: uuid::Uuid) {
+        *self.session.user.lock().unwrap_or_else(|e| e.into_inner()) = Some(user);
+    }
+
+    pub async fn rooms(&self) -> HashSet<String> {
+        self.session
+            .namespaces
+            .lock()
+            .await
+            .get(&self.namespace)
+            .map(|state| state.rooms.clone())
+            .unwrap_or_default()
+    }
+
+    pub async fn auth(&self) -> Option<Value> {
+        self.session
+            .namespaces
+            .lock()
+            .await
+            .get(&self.namespace)
+            .and_then(|state| state.auth.clone())
+    }
+
+    pub async fn emit<T: Serialize>(&self, event: &str, data: T) -> Result<()> {
+        self.io
+            .emit_to_sid(&self.namespace, &self.session.engine_id, event, data)
+            .await
+    }
+
+    pub async fn emit_with_ack<T: Serialize>(
+        &self,
+        event: &str,
+        data: T,
+    ) -> Result<Vec<Value>> {
+        self.io
+            .emit_to_sid_with_ack(
+                &self.namespace,
+                &self.session.engine_id,
+                event,
+                data,
+            )
+            .await
+    }
+
+    pub async fn emit_binary(
+        &self,
+        event: &str,
+        args: Vec<Value>,
+        binary: Vec<Vec<u8>>,
+    ) -> Result<()> {
+        self.io
+            .emit_binary_to_sid(
+                &self.namespace,
+                &self.session.engine_id,
+                event,
+                args,
+                binary,
+            )
+            .await
+    }
+
+    pub async fn broadcast<T: Serialize>(
+        &self,
+        event: &str,
+        data: T,
+    ) -> Result<()> {
+        let opts = BroadcastOptions {
+            namespace: self.namespace.clone(),
+            skip_sid: Some(self.session.engine_id.clone()),
+            ..BroadcastOptions::default()
+        };
+        self.io.broadcast_with_opts(opts, event, data).await
+    }
+
+    pub async fn join(&self, room: impl Into<String>) -> Result<()> {
+        self.io
+            .join(&self.namespace, &self.session.engine_id, room.into())
+            .await
+    }
+
+    pub async fn leave(&self, room: &str) -> Result<()> {
+        self.io
+            .leave(&self.namespace, &self.session.engine_id, room)
+            .await
+    }
+
+    pub async fn disconnect(&self) -> Result<()> {
+        self.session
+            .enqueue_socket_packet(Packet::new(
+                crate::packet::PacketType::Disconnect,
+                &self.namespace,
+                None,
+                None,
+            ))
+            .await;
+        self.io
+            .disconnect_socket(
+                &self.namespace,
+                &self.session,
+                DisconnectReason::Server,
+            )
+            .await
+    }
+}
diff --git a/lib/storage/Cargo.toml b/lib/storage/Cargo.toml
new file mode 100644
index 0000000..0c3b4b4
--- /dev/null
+++ b/lib/storage/Cargo.toml
@@ -0,0 +1,30 @@
+[package]
+name = "storage"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+description.workspace = true
+repository.workspace = true
+readme.workspace = true
+homepage.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+documentation.workspace = true
+
+
+[lib]
+path = "lib.rs"
+name = "storage"
+[dependencies]
+async-trait = { workspace = true }
+aws-config = { workspace = true }
+aws-sdk-s3 = { workspace = true }
+config = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["fs", "io-util", "macros", "rt-multi-thread"] }
+
+[lints]
+workspace = true
diff --git a/lib/storage/error.rs b/lib/storage/error.rs
new file mode 100644
index 0000000..9bb77c4
--- /dev/null
+++ b/lib/storage/error.rs
@@ -0,0 +1,17 @@
+pub type StorageResult<T> = Result<T, StorageError>;
+
+#[derive(Debug, thiserror::Error)]
+pub enum StorageError {
+    #[error("storage config error: {0}")]
+    Config(String),
+    #[error("invalid storage key: {0}")]
+    InvalidKey(String),
+    #[error("storage object not found: {0}")]
+    NotFound(String),
+    #[error("local storage error: {0}")]
+    Local(String),
+    #[error("s3 error: {0}")]
+    S3(String),
+    #[error("stream error: {0}")]
+    Stream(String),
+}
diff --git a/lib/storage/lib.rs b/lib/storage/lib.rs
new file mode 100644
index 0000000..dd89ef6
--- /dev/null
+++ b/lib/storage/lib.rs
@@ -0,0 +1,202 @@
+pub mod error;
+pub mod local;
+pub mod s3;
+
+use std::time::Duration;
+
+use async_trait::async_trait;
+pub use aws_sdk_s3::primitives::ByteStream;
+use aws_sdk_s3::primitives::ByteStreamError;
+pub use error::{StorageError, StorageResult};
+pub use local::{LocalStorage, LocalStorageConfig};
+pub use s3::{S3Storage, S3StorageConfig};
+
+#[derive(Clone, Debug)]
+pub enum AppStorageConfig {
+    Local(LocalStorageConfig),
+    S3(S3StorageConfig),
+}
+
+#[derive(Clone)]
+pub enum AppStorage {
+    Local(LocalStorage),
+    S3(S3Storage),
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct PutObjectOptions {
+    pub content_type: Option<String>,
+    pub content_length: Option<i64>,
+    pub cache_control: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+pub struct StoredObject {
+    pub key: String,
+    pub url: String,
+    pub e_tag: Option<String>,
+    pub version_id: Option<String>,
+}
+
+#[derive(Debug)]
+pub struct StorageObjectStream {
+    pub body: ByteStream,
+    pub content_length: Option<i64>,
+    pub content_type: Option<String>,
+    pub e_tag: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+pub struct StorageObject {
+    pub bytes: Vec<u8>,
+    pub content_length: Option<i64>,
+    pub content_type: Option<String>,
+    pub e_tag: Option<String>,
+}
+
+#[async_trait]
+pub trait ObjectStorage: Send + Sync {
+    async fn put_stream(
+        &self,
+        key: &str,
+        body: ByteStream,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject>;
+
+    async fn put_bytes(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject>;
+
+    async fn get_stream(&self, key: &str)
+    -> StorageResult<StorageObjectStream>;
+
+    async fn get_bytes(&self, key: &str) -> StorageResult<StorageObject>;
+
+    async fn delete(&self, key: &str) -> StorageResult<()>;
+
+    fn public_url(&self, key: &str) -> StorageResult<Option<String>>;
+
+    async fn presigned_get_url(
+        &self,
+        key: &str,
+        expires_in: Duration,
+    ) -> StorageResult<String>;
+}
+
+impl AppStorage {
+    pub async fn init(config: AppStorageConfig) -> StorageResult<Self> {
+        match config {
+            AppStorageConfig::Local(config) => {
+                Ok(Self::Local(LocalStorage::connect(config).await?))
+            }
+            AppStorageConfig::S3(config) => {
+                Ok(Self::S3(S3Storage::connect(config).await?))
+            }
+        }
+    }
+}
+
+#[async_trait]
+impl ObjectStorage for AppStorage {
+    async fn put_stream(
+        &self,
+        key: &str,
+        body: ByteStream,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        match self {
+            Self::Local(storage) => {
+                storage.put_stream(key, body, options).await
+            }
+            Self::S3(storage) => storage.put_stream(key, body, options).await,
+        }
+    }
+
+    async fn put_bytes(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        match self {
+            Self::Local(storage) => {
+                storage.put_bytes(key, bytes, options).await
+            }
+            Self::S3(storage) => storage.put_bytes(key, bytes, options).await,
+        }
+    }
+
+    async fn get_stream(
+        &self,
+        key: &str,
+    ) -> StorageResult<StorageObjectStream> {
+        match self {
+            Self::Local(storage) => storage.get_stream(key).await,
+            Self::S3(storage) => storage.get_stream(key).await,
+        }
+    }
+
+    async fn get_bytes(&self, key: &str) -> StorageResult<StorageObject> {
+        match self {
+            Self::Local(storage) => storage.get_bytes(key).await,
+            Self::S3(storage) => storage.get_bytes(key).await,
+        }
+    }
+
+    async fn delete(&self, key: &str) -> StorageResult<()> {
+        match self {
+            Self::Local(storage) => storage.delete(key).await,
+            Self::S3(storage) => storage.delete(key).await,
+        }
+    }
+
+    fn public_url(&self, key: &str) -> StorageResult<Option<String>> {
+        match self {
+            Self::Local(storage) => storage.public_url(key),
+            Self::S3(storage) => storage.public_url(key),
+        }
+    }
+
+    async fn presigned_get_url(
+        &self,
+        key: &str,
+        expires_in: Duration,
+    ) -> StorageResult<String> {
+        match self {
+            Self::Local(storage) => {
+                storage.presigned_get_url(key, expires_in).await
+            }
+            Self::S3(storage) => {
+                storage.presigned_get_url(key, expires_in).await
+            }
+        }
+    }
+}
+
+pub(crate) async fn collect_byte_stream(
+    body: ByteStream,
+) -> Result<Vec<u8>, ByteStreamError> {
+    body.collect().await.map(|data| data.to_vec())
+}
+
+impl TryFrom<&config::AppConfig> for AppStorageConfig {
+    type Error = StorageError;
+
+    fn try_from(config: &config::AppConfig) -> Result<Self, Self::Error> {
+        let backend = config
+            .storage_backend()
+            .map_err(|error| StorageError::Config(error.to_string()))?;
+        match backend.as_str() {
+            "local" | "fs" | "filesystem" => {
+                Ok(Self::Local(LocalStorageConfig::try_from(config)?))
+            }
+            "s3" => Ok(Self::S3(S3StorageConfig::try_from(config)?)),
+            backend => Err(StorageError::Config(format!(
+                "unsupported storage backend: {backend}"
+            ))),
+        }
+    }
+}
diff --git a/lib/storage/local.rs b/lib/storage/local.rs
new file mode 100644
index 0000000..75271da
--- /dev/null
+++ b/lib/storage/local.rs
@@ -0,0 +1,380 @@
+use std::{
+    path::{Component, Path, PathBuf},
+    time::Duration,
+};
+
+use async_trait::async_trait;
+use aws_sdk_s3::primitives::ByteStream;
+use serde::{Deserialize, Serialize};
+use tokio::fs;
+
+use crate::{
+    ObjectStorage, PutObjectOptions, StorageError, StorageObject,
+    StorageObjectStream, StorageResult, StoredObject,
+};
+
+#[derive(Clone, Debug)]
+pub struct LocalStorageConfig {
+    pub root_path: PathBuf,
+    pub public_url: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct LocalStorage {
+    config: LocalStorageConfig,
+}
+
+#[derive(Clone, Debug, Default, Deserialize, Serialize)]
+struct LocalObjectMetadata {
+    content_type: Option<String>,
+}
+
+impl LocalStorage {
+    pub async fn connect(config: LocalStorageConfig) -> StorageResult<Self> {
+        if config.root_path.as_os_str().is_empty() {
+            return Err(StorageError::Config(
+                "local storage root path cannot be empty".to_string(),
+            ));
+        }
+
+        fs::create_dir_all(&config.root_path)
+            .await
+            .map_err(|error| StorageError::Local(error.to_string()))?;
+
+        Ok(Self { config })
+    }
+
+    pub async fn put_bytes(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        self.put_stream(key, ByteStream::from(bytes), options).await
+    }
+
+    fn normalize_key(key: &str) -> StorageResult<String> {
+        let key = key.trim().trim_start_matches('/');
+        if key.is_empty() {
+            return Err(StorageError::InvalidKey(key.to_string()));
+        }
+
+        let mut parts = Vec::new();
+        for component in Path::new(key).components() {
+            match component {
+                Component::Normal(part) => {
+                    let part = part.to_str().ok_or_else(|| {
+                        StorageError::InvalidKey(key.to_string())
+                    })?;
+                    parts.push(part);
+                }
+                Component::CurDir
+                | Component::ParentDir
+                | Component::RootDir
+                | Component::Prefix(_) => {
+                    return Err(StorageError::InvalidKey(key.to_string()));
+                }
+            }
+        }
+
+        if parts.is_empty() {
+            return Err(StorageError::InvalidKey(key.to_string()));
+        }
+
+        Ok(parts.join("/"))
+    }
+
+    fn object_path(&self, key: &str) -> PathBuf {
+        self.config.root_path.join(key)
+    }
+
+    fn metadata_path(&self, key: &str) -> PathBuf {
+        self.config
+            .root_path
+            .join(".metadata")
+            .join(format!("{key}.json"))
+    }
+
+    fn public_url_for_config(
+        config: &LocalStorageConfig,
+        key: &str,
+    ) -> Option<String> {
+        let base_url = config.public_url.as_ref()?.trim_end_matches('/');
+        Some(format!("{base_url}/{key}"))
+    }
+
+    async fn write_metadata(
+        &self,
+        key: &str,
+        metadata: &LocalObjectMetadata,
+    ) -> StorageResult<()> {
+        let path = self.metadata_path(key);
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent)
+                .await
+                .map_err(|error| StorageError::Local(error.to_string()))?;
+        }
+
+        let bytes = serde_json::to_vec(metadata)
+            .map_err(|error| StorageError::Local(error.to_string()))?;
+        fs::write(path, bytes)
+            .await
+            .map_err(|error| StorageError::Local(error.to_string()))
+    }
+
+    async fn read_metadata(
+        &self,
+        key: &str,
+    ) -> StorageResult<LocalObjectMetadata> {
+        let path = self.metadata_path(key);
+        let bytes = fs::read(path).await.map_err(|error| {
+            if error.kind() == std::io::ErrorKind::NotFound {
+                StorageError::NotFound(key.to_string())
+            } else {
+                StorageError::Local(error.to_string())
+            }
+        })?;
+        serde_json::from_slice(&bytes)
+            .map_err(|error| StorageError::Local(error.to_string()))
+    }
+}
+
+#[async_trait]
+impl ObjectStorage for LocalStorage {
+    async fn put_stream(
+        &self,
+        key: &str,
+        body: ByteStream,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        let key = Self::normalize_key(key)?;
+        let path = self.object_path(&key);
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent)
+                .await
+                .map_err(|error| StorageError::Local(error.to_string()))?;
+        }
+
+        let bytes = crate::collect_byte_stream(body)
+            .await
+            .map_err(|error| StorageError::Stream(error.to_string()))?;
+        if let Some(content_length) = options.content_length
+            && content_length >= 0
+            && bytes.len() as i64 != content_length
+        {
+            return Err(StorageError::Local(format!(
+                "content length mismatch for {key}: expected {content_length}, got {}",
+                bytes.len()
+            )));
+        }
+
+        let metadata = LocalObjectMetadata {
+            content_type: options.content_type,
+        };
+
+        fs::write(&path, bytes)
+            .await
+            .map_err(|error| StorageError::Local(error.to_string()))?;
+        self.write_metadata(&key, &metadata).await?;
+
+        Ok(StoredObject {
+            url: self.public_url(&key)?.unwrap_or_else(|| key.clone()),
+            key,
+            e_tag: None,
+            version_id: None,
+        })
+    }
+
+    async fn put_bytes(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        LocalStorage::put_bytes(self, key, bytes, options).await
+    }
+
+    async fn get_stream(
+        &self,
+        key: &str,
+    ) -> StorageResult<StorageObjectStream> {
+        let key = Self::normalize_key(key)?;
+        let path = self.object_path(&key);
+        let metadata = fs::metadata(&path).await.map_err(|error| {
+            if error.kind() == std::io::ErrorKind::NotFound {
+                StorageError::NotFound(key.clone())
+            } else {
+                StorageError::Local(error.to_string())
+            }
+        })?;
+        let object_metadata = match self.read_metadata(&key).await {
+            Ok(metadata) => metadata,
+            Err(StorageError::NotFound(_)) => LocalObjectMetadata::default(),
+            Err(error) => return Err(error),
+        };
+        let body = ByteStream::from_path(&path)
+            .await
+            .map_err(|error| StorageError::Stream(error.to_string()))?;
+
+        Ok(StorageObjectStream {
+            body,
+            content_length: Some(metadata.len() as i64),
+            content_type: object_metadata.content_type,
+            e_tag: None,
+        })
+    }
+
+    async fn get_bytes(&self, key: &str) -> StorageResult<StorageObject> {
+        let stream = self.get_stream(key).await?;
+        let bytes = crate::collect_byte_stream(stream.body)
+            .await
+            .map_err(|error| StorageError::Stream(error.to_string()))?;
+
+        Ok(StorageObject {
+            bytes,
+            content_length: stream.content_length,
+            content_type: stream.content_type,
+            e_tag: stream.e_tag,
+        })
+    }
+
+    async fn delete(&self, key: &str) -> StorageResult<()> {
+        let key = Self::normalize_key(key)?;
+        let path = self.object_path(&key);
+        fs::remove_file(path).await.map_or_else(
+            |error| {
+                if error.kind() == std::io::ErrorKind::NotFound {
+                    Ok(())
+                } else {
+                    Err(StorageError::Local(error.to_string()))
+                }
+            },
+            |_| Ok(()),
+        )?;
+        fs::remove_file(self.metadata_path(&key)).await.map_or_else(
+            |error| {
+                if error.kind() == std::io::ErrorKind::NotFound {
+                    Ok(())
+                } else {
+                    Err(StorageError::Local(error.to_string()))
+                }
+            },
+            |_| Ok(()),
+        )
+    }
+
+    fn public_url(&self, key: &str) -> StorageResult<Option<String>> {
+        let key = Self::normalize_key(key)?;
+        Ok(Self::public_url_for_config(&self.config, &key))
+    }
+
+    async fn presigned_get_url(
+        &self,
+        key: &str,
+        _expires_in: Duration,
+    ) -> StorageResult<String> {
+        self.public_url(key)?.ok_or_else(|| {
+            StorageError::Config(
+                "local storage public URL is not configured".to_string(),
+            )
+        })
+    }
+}
+
+impl TryFrom<&config::AppConfig> for LocalStorageConfig {
+    type Error = StorageError;
+
+    fn try_from(config: &config::AppConfig) -> Result<Self, Self::Error> {
+        Ok(Self {
+            root_path: PathBuf::from(config.storage_path()),
+            public_url: Some(config.storage_public_url()),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    use tokio::fs;
+
+    use super::{LocalStorage, LocalStorageConfig};
+    use crate::{ObjectStorage, PutObjectOptions, StorageError};
+
+    fn temp_root() -> Result<std::path::PathBuf, StorageError> {
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_err(|error| StorageError::Local(error.to_string()))?
+            .as_nanos();
+        Ok(std::env::temp_dir().join(format!(
+            "gitdataai-local-storage-{}-{nanos}",
+            std::process::id()
+        )))
+    }
+
+    #[tokio::test]
+    async fn stores_reads_and_deletes_bytes() -> Result<(), StorageError> {
+        let root = temp_root()?;
+        let storage = LocalStorage::connect(LocalStorageConfig {
+            root_path: root.clone(),
+            public_url: Some("/files".to_string()),
+        })
+        .await?;
+
+        let stored = storage
+            .put_bytes(
+                "avatars/user-1.txt",
+                b"hello".to_vec(),
+                PutObjectOptions {
+                    content_type: Some("text/plain".to_string()),
+                    content_length: Some(5),
+                    ..PutObjectOptions::default()
+                },
+            )
+            .await?;
+        assert_eq!(stored.key, "avatars/user-1.txt");
+        assert_eq!(stored.url, "/files/avatars/user-1.txt");
+
+        let object = storage.get_bytes("avatars/user-1.txt").await?;
+        assert_eq!(object.bytes, b"hello");
+        assert_eq!(object.content_length, Some(5));
+        assert_eq!(object.content_type.as_deref(), Some("text/plain"));
+
+        storage.delete("avatars/user-1.txt").await?;
+        assert!(matches!(
+            storage.get_bytes("avatars/user-1.txt").await,
+            Err(StorageError::NotFound(_))
+        ));
+
+        fs::remove_dir_all(root)
+            .await
+            .map_err(|error| StorageError::Local(error.to_string()))?;
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn rejects_path_traversal_keys() -> Result<(), StorageError> {
+        let storage = LocalStorage::connect(LocalStorageConfig {
+            root_path: temp_root()?,
+            public_url: Some("/files".to_string()),
+        })
+        .await?;
+
+        assert!(matches!(
+            storage
+                .put_bytes(
+                    "../escape.txt",
+                    b"bad".to_vec(),
+                    PutObjectOptions::default()
+                )
+                .await,
+            Err(StorageError::InvalidKey(_))
+        ));
+        assert!(matches!(
+            storage.public_url("nested/../escape.txt"),
+            Err(StorageError::InvalidKey(_))
+        ));
+
+        Ok(())
+    }
+}
diff --git a/lib/storage/s3.rs b/lib/storage/s3.rs
new file mode 100644
index 0000000..da700c0
--- /dev/null
+++ b/lib/storage/s3.rs
@@ -0,0 +1,265 @@
+use std::time::Duration;
+
+use async_trait::async_trait;
+use aws_config::BehaviorVersion;
+use aws_sdk_s3::{
+    Client,
+    config::{Credentials, Region},
+    presigning::PresigningConfig,
+    primitives::ByteStream,
+};
+
+use crate::{
+    ObjectStorage, PutObjectOptions, StorageError, StorageObject,
+    StorageObjectStream, StorageResult, StoredObject,
+};
+
+#[derive(Clone, Debug)]
+pub struct S3StorageConfig {
+    pub bucket: String,
+    pub region: String,
+    pub endpoint_url: Option<String>,
+    pub access_key_id: Option<String>,
+    pub secret_access_key: Option<String>,
+    pub session_token: Option<String>,
+    pub force_path_style: bool,
+    pub public_url: Option<String>,
+    pub presigned_url_ttl: Duration,
+}
+
+#[derive(Clone)]
+pub struct S3Storage {
+    client: Client,
+    config: S3StorageConfig,
+}
+
+impl S3Storage {
+    pub async fn connect(config: S3StorageConfig) -> StorageResult<Self> {
+        let mut sdk_config = aws_config::defaults(BehaviorVersion::latest())
+            .region(Region::new(config.region.clone()));
+
+        match (&config.access_key_id, &config.secret_access_key) {
+            (Some(access_key_id), Some(secret_access_key)) => {
+                sdk_config = sdk_config.credentials_provider(Credentials::new(
+                    access_key_id,
+                    secret_access_key,
+                    config.session_token.clone(),
+                    None,
+                    "app-storage-config",
+                ));
+            }
+            (None, None) => {}
+            _ => {
+                return Err(StorageError::Config(
+                    "APP_STORAGE_S3_ACCESS_KEY_ID and APP_STORAGE_S3_SECRET_ACCESS_KEY must be set together"
+                        .to_string(),
+                ));
+            }
+        }
+
+        let sdk_config = sdk_config.load().await;
+        let mut s3_config = aws_sdk_s3::config::Builder::from(&sdk_config)
+            .force_path_style(config.force_path_style);
+
+        if let Some(endpoint_url) = &config.endpoint_url {
+            s3_config = s3_config.endpoint_url(endpoint_url);
+        }
+
+        Ok(Self {
+            client: Client::from_conf(s3_config.build()),
+            config,
+        })
+    }
+
+    pub async fn put_bytes(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        self.put_stream(key, ByteStream::from(bytes), options).await
+    }
+
+    pub async fn put_file(
+        &self,
+        key: &str,
+        path: impl AsRef<std::path::Path>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        let body = ByteStream::read_from()
+            .path(path.as_ref())
+            .build()
+            .await
+            .map_err(|error| StorageError::Stream(error.to_string()))?;
+        self.put_stream(key, body, options).await
+    }
+
+    fn normalize_key(key: &str) -> StorageResult<String> {
+        let key = key.trim().trim_start_matches('/');
+        if key.is_empty() || key.contains("..") {
+            return Err(StorageError::InvalidKey(key.to_string()));
+        }
+        Ok(key.to_string())
+    }
+
+    fn public_url_for_config(
+        config: &S3StorageConfig,
+        key: &str,
+    ) -> Option<String> {
+        let base_url = config.public_url.as_ref()?.trim_end_matches('/');
+        Some(format!("{base_url}/{key}"))
+    }
+}
+
+#[async_trait]
+impl ObjectStorage for S3Storage {
+    async fn put_stream(
+        &self,
+        key: &str,
+        body: ByteStream,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        let key = Self::normalize_key(key)?;
+
+        let mut request = self
+            .client
+            .put_object()
+            .bucket(&self.config.bucket)
+            .key(&key)
+            .body(body);
+
+        if let Some(content_type) = options.content_type {
+            request = request.content_type(content_type);
+        }
+        if let Some(content_length) = options.content_length {
+            request = request.content_length(content_length);
+        }
+        if let Some(cache_control) = options.cache_control {
+            request = request.cache_control(cache_control);
+        }
+
+        let output = request
+            .send()
+            .await
+            .map_err(|error| StorageError::S3(error.to_string()))?;
+        let url = match self.public_url(&key)? {
+            Some(url) => url,
+            None => {
+                self.presigned_get_url(&key, self.config.presigned_url_ttl)
+                    .await?
+            }
+        };
+
+        Ok(StoredObject {
+            key,
+            url,
+            e_tag: output.e_tag,
+            version_id: output.version_id,
+        })
+    }
+
+    async fn put_bytes(
+        &self,
+        key: &str,
+        bytes: Vec<u8>,
+        options: PutObjectOptions,
+    ) -> StorageResult<StoredObject> {
+        S3Storage::put_bytes(self, key, bytes, options).await
+    }
+
+    async fn get_stream(
+        &self,
+        key: &str,
+    ) -> StorageResult<StorageObjectStream> {
+        let key = Self::normalize_key(key)?;
+        let output = self
+            .client
+            .get_object()
+            .bucket(&self.config.bucket)
+            .key(&key)
+            .send()
+            .await
+            .map_err(|error| StorageError::S3(error.to_string()))?;
+
+        Ok(StorageObjectStream {
+            body: output.body,
+            content_length: output.content_length,
+            content_type: output.content_type,
+            e_tag: output.e_tag,
+        })
+    }
+
+    async fn get_bytes(&self, key: &str) -> StorageResult<StorageObject> {
+        let stream = self.get_stream(key).await?;
+        let bytes = crate::collect_byte_stream(stream.body)
+            .await
+            .map_err(|error| StorageError::Stream(error.to_string()))?;
+
+        Ok(StorageObject {
+            bytes,
+            content_length: stream.content_length,
+            content_type: stream.content_type,
+            e_tag: stream.e_tag,
+        })
+    }
+
+    async fn delete(&self, key: &str) -> StorageResult<()> {
+        let key = Self::normalize_key(key)?;
+        self.client
+            .delete_object()
+            .bucket(&self.config.bucket)
+            .key(key)
+            .send()
+            .await
+            .map_err(|error| StorageError::S3(error.to_string()))?;
+        Ok(())
+    }
+
+    fn public_url(&self, key: &str) -> StorageResult<Option<String>> {
+        let key = Self::normalize_key(key)?;
+        Ok(Self::public_url_for_config(&self.config, &key))
+    }
+
+    async fn presigned_get_url(
+        &self,
+        key: &str,
+        expires_in: Duration,
+    ) -> StorageResult<String> {
+        let key = Self::normalize_key(key)?;
+        let config = PresigningConfig::expires_in(expires_in)
+            .map_err(|error| StorageError::Config(error.to_string()))?;
+        let request = self
+            .client
+            .get_object()
+            .bucket(&self.config.bucket)
+            .key(key)
+            .presigned(config)
+            .await
+            .map_err(|error| StorageError::S3(error.to_string()))?;
+        Ok(request.uri().to_string())
+    }
+}
+
+impl TryFrom<&config::AppConfig> for S3StorageConfig {
+    type Error = StorageError;
+
+    fn try_from(config: &config::AppConfig) -> Result<Self, Self::Error> {
+        Ok(Self {
+            bucket: config
+                .storage_s3_bucket()
+                .map_err(|error| StorageError::Config(error.to_string()))?,
+            region: config.storage_s3_region(),
+            endpoint_url: config.storage_s3_endpoint_url(),
+            access_key_id: config.storage_s3_access_key_id(),
+            secret_access_key: config.storage_s3_secret_access_key(),
+            session_token: config.storage_s3_session_token(),
+            force_path_style: config
+                .storage_s3_force_path_style()
+                .map_err(|error| StorageError::Config(error.to_string()))?,
+            public_url: config.storage_public_url_base(),
+            presigned_url_ttl: config
+                .storage_presigned_url_ttl()
+                .map_err(|error| StorageError::Config(error.to_string()))?,
+        })
+    }
+}
diff --git a/public/favicon.svg b/public/favicon.svg
new file mode 100644
index 0000000..6893eb1
--- /dev/null
+++ b/public/favicon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="46" fill="none" viewBox="0 0 48 46"><path fill="#863bff" d="M25.946 44.938c-.664.845-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.287c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.497 0-3.578-1.842-3.578H1.237c-.92 0-1.456-1.04-.92-1.788L10.013.474c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.579 1.842 3.579h11.377c.943 0 1.473 1.088.89 1.83L25.947 44.94z" style="fill:#863bff;fill:color(display-p3 .5252 .23 1);fill-opacity:1"/><mask id="a" width="48" height="46" x="0" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#000" d="M25.842 44.938c-.664.844-2.021.375-2.021-.698V33.937a2.26 2.26 0 0 0-2.262-2.262H10.183c-.92 0-1.456-1.04-.92-1.788l7.48-10.471c1.07-1.498 0-3.579-1.842-3.579H1.133c-.92 0-1.456-1.04-.92-1.787L9.91.473c.214-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.471c-1.07 1.498 0 3.578 1.842 3.578h11.377c.943 0 1.473 1.088.89 1.832L25.843 44.94z" style="fill:#000;fill-opacity:1"/></mask><g mask="url(#a)"><g filter="url(#b)"><ellipse cx="5.508" cy="14.704" fill="#ede6ff" rx="5.508" ry="14.704" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -4.47 31.516)"/></g><g filter="url(#c)"><ellipse cx="10.399" cy="29.851" fill="#ede6ff" rx="10.399" ry="29.851" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -39.328 7.883)"/></g><g filter="url(#d)"><ellipse cx="5.508" cy="30.487" fill="#7e14ff" rx="5.508" ry="30.487" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -25.913 -14.639)scale(1 -1)"/></g><g filter="url(#e)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.814 -32.644 -3.334)scale(1 -1)"/></g><g filter="url(#f)"><ellipse cx="5.508" cy="30.599" fill="#7e14ff" rx="5.508" ry="30.599" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="matrix(.00324 1 1 -.00324 -34.34 30.47)"/></g><g filter="url(#g)"><ellipse cx="14.072" cy="22.078" fill="#ede6ff" rx="14.072" ry="22.078" style="fill:#ede6ff;fill:color(display-p3 .9275 .9033 1);fill-opacity:1" transform="rotate(93.35 24.506 48.493)scale(-1 1)"/></g><g filter="url(#h)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#i)"><ellipse cx="3.47" cy="21.501" fill="#7e14ff" rx="3.47" ry="21.501" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(89.009 28.708 47.59)scale(-1 1)"/></g><g filter="url(#j)"><ellipse cx=".387" cy="8.972" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(39.51 .387 8.972)"/></g><g filter="url(#k)"><ellipse cx="47.523" cy="-6.092" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 47.523 -6.092)"/></g><g filter="url(#l)"><ellipse cx="41.412" cy="6.333" fill="#47bfff" rx="5.971" ry="9.665" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 41.412 6.333)"/></g><g filter="url(#m)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#n)"><ellipse cx="-1.879" cy="38.332" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 -1.88 38.332)"/></g><g filter="url(#o)"><ellipse cx="35.651" cy="29.907" fill="#7e14ff" rx="4.407" ry="29.108" style="fill:#7e14ff;fill:color(display-p3 .4922 .0767 1);fill-opacity:1" transform="rotate(37.892 35.651 29.907)"/></g><g filter="url(#p)"><ellipse cx="38.418" cy="32.4" fill="#47bfff" rx="5.971" ry="15.297" style="fill:#47bfff;fill:color(display-p3 .2799 .748 1);fill-opacity:1" transform="rotate(37.892 38.418 32.4)"/></g></g><defs><filter id="b" width="60.045" height="41.654" x="-19.77" y="16.149" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="c" width="90.34" height="51.437" x="-54.613" y="-7.533" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="d" width="79.355" height="29.4" x="-49.64" y="2.03" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="e" width="79.579" height="29.4" x="-45.045" y="20.029" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="f" width="79.579" height="29.4" x="-43.513" y="21.178" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="g" width="74.749" height="58.852" x="15.756" y="-17.901" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="7.659"/></filter><filter id="h" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="i" width="61.377" height="25.362" x="23.548" y="2.284" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="j" width="56.045" height="63.649" x="-27.636" y="-22.853" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="k" width="54.814" height="64.646" x="20.116" y="-38.415" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="l" width="33.541" height="35.313" x="24.641" y="-11.323" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="m" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="n" width="54.814" height="64.646" x="-29.286" y="6.009" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="o" width="54.814" height="64.646" x="8.244" y="-2.416" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter><filter id="p" width="39.409" height="43.623" x="18.713" y="10.588" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17158" stdDeviation="4.596"/></filter></defs></svg>
\ No newline at end of file
diff --git a/public/icons.svg b/public/icons.svg
new file mode 100644
index 0000000..e952219
--- /dev/null
+++ b/public/icons.svg
@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg">
+  <symbol id="bluesky-icon" viewBox="0 0 16 17">
+    <g clip-path="url(#bluesky-clip)"><path fill="#08060d" d="M7.75 7.735c-.693-1.348-2.58-3.86-4.334-5.097-1.68-1.187-2.32-.981-2.74-.79C.188 2.065.1 2.812.1 3.251s.241 3.602.398 4.13c.52 1.744 2.367 2.333 4.07 2.145-2.495.37-4.71 1.278-1.805 4.512 3.196 3.309 4.38-.71 4.987-2.746.608 2.036 1.307 5.91 4.93 2.746 2.72-2.746.747-4.143-1.747-4.512 1.702.189 3.55-.4 4.07-2.145.156-.528.397-3.691.397-4.13s-.088-1.186-.575-1.406c-.42-.19-1.06-.395-2.741.79-1.755 1.24-3.64 3.752-4.334 5.099"/></g>
+    <defs><clipPath id="bluesky-clip"><path fill="#fff" d="M.1.85h15.3v15.3H.1z"/></clipPath></defs>
+  </symbol>
+  <symbol id="discord-icon" viewBox="0 0 20 19">
+    <path fill="#08060d" d="M16.224 3.768a14.5 14.5 0 0 0-3.67-1.153c-.158.286-.343.67-.47.976a13.5 13.5 0 0 0-4.067 0c-.128-.306-.317-.69-.476-.976A14.4 14.4 0 0 0 3.868 3.77C1.546 7.28.916 10.703 1.231 14.077a14.7 14.7 0 0 0 4.5 2.306q.545-.748.965-1.587a9.5 9.5 0 0 1-1.518-.74q.191-.14.372-.293c2.927 1.369 6.107 1.369 8.999 0q.183.152.372.294-.723.437-1.52.74.418.838.963 1.588a14.6 14.6 0 0 0 4.504-2.308c.37-3.911-.63-7.302-2.644-10.309m-9.13 8.234c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.894 0 1.614.82 1.599 1.82.001 1-.705 1.82-1.6 1.82m5.91 0c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.893 0 1.614.82 1.599 1.82 0 1-.706 1.82-1.6 1.82"/>
+  </symbol>
+  <symbol id="documentation-icon" viewBox="0 0 21 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="m15.5 13.333 1.533 1.322c.645.555.967.833.967 1.178s-.322.623-.967 1.179L15.5 18.333m-3.333-5-1.534 1.322c-.644.555-.966.833-.966 1.178s.322.623.966 1.179l1.534 1.321"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M17.167 10.836v-4.32c0-1.41 0-2.117-.224-2.68-.359-.906-1.118-1.621-2.08-1.96-.599-.21-1.349-.21-2.848-.21-2.623 0-3.935 0-4.983.369-1.684.591-3.013 1.842-3.641 3.428C3 6.449 3 7.684 3 10.154v2.122c0 2.558 0 3.838.706 4.726q.306.383.713.671c.76.536 1.79.64 3.581.66"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M3 10a2.78 2.78 0 0 1 2.778-2.778c.555 0 1.209.097 1.748-.047.48-.129.854-.503.982-.982.145-.54.048-1.194.048-1.749a2.78 2.78 0 0 1 2.777-2.777"/>
+  </symbol>
+  <symbol id="github-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M9.356 1.85C5.05 1.85 1.57 5.356 1.57 9.694a7.84 7.84 0 0 0 5.324 7.44c.387.079.528-.168.528-.376 0-.182-.013-.805-.013-1.454-2.165.467-2.616-.935-2.616-.935-.349-.91-.864-1.143-.864-1.143-.71-.48.051-.48.051-.48.787.051 1.2.805 1.2.805.695 1.194 1.817.857 2.268.649.064-.507.27-.857.49-1.052-1.728-.182-3.545-.857-3.545-3.87 0-.857.31-1.558.8-2.104-.078-.195-.349-1 .077-2.078 0 0 .657-.208 2.14.805a7.5 7.5 0 0 1 1.946-.26c.657 0 1.328.092 1.946.26 1.483-1.013 2.14-.805 2.14-.805.426 1.078.155 1.883.078 2.078.502.546.799 1.247.799 2.104 0 3.013-1.818 3.675-3.558 3.87.284.247.528.714.528 1.454 0 1.052-.012 1.896-.012 2.156 0 .208.142.455.528.377a7.84 7.84 0 0 0 5.324-7.441c.013-4.338-3.48-7.844-7.773-7.844" clip-rule="evenodd"/>
+  </symbol>
+  <symbol id="social-icon" viewBox="0 0 20 20">
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M12.5 6.667a4.167 4.167 0 1 0-8.334 0 4.167 4.167 0 0 0 8.334 0"/>
+    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M2.5 16.667a5.833 5.833 0 0 1 8.75-5.053m3.837.474.513 1.035c.07.144.257.282.414.309l.93.155c.596.1.736.536.307.965l-.723.73a.64.64 0 0 0-.152.531l.207.903c.164.715-.213.991-.84.618l-.872-.52a.63.63 0 0 0-.577 0l-.872.52c-.624.373-1.003.094-.84-.618l.207-.903a.64.64 0 0 0-.152-.532l-.723-.729c-.426-.43-.289-.864.306-.964l.93-.156a.64.64 0 0 0 .412-.31l.513-1.034c.28-.562.735-.562 1.012 0"/>
+  </symbol>
+  <symbol id="x-icon" viewBox="0 0 19 19">
+    <path fill="#08060d" fill-rule="evenodd" d="M1.893 1.98c.052.072 1.245 1.769 2.653 3.77l2.892 4.114c.183.261.333.48.333.486s-.068.089-.152.183l-.522.593-.765.867-3.597 4.087c-.375.426-.734.834-.798.905a1 1 0 0 0-.118.148c0 .01.236.017.664.017h.663l.729-.83c.4-.457.796-.906.879-.999a692 692 0 0 0 1.794-2.038c.034-.037.301-.34.594-.675l.551-.624.345-.392a7 7 0 0 1 .34-.374c.006 0 .93 1.306 2.052 2.903l2.084 2.965.045.063h2.275c1.87 0 2.273-.003 2.266-.021-.008-.02-1.098-1.572-3.894-5.547-2.013-2.862-2.28-3.246-2.273-3.266.008-.019.282-.332 2.085-2.38l2-2.274 1.567-1.782c.022-.028-.016-.03-.65-.03h-.674l-.3.342a871 871 0 0 1-1.782 2.025c-.067.075-.405.458-.75.852a100 100 0 0 1-.803.91c-.148.172-.299.344-.99 1.127-.304.343-.32.358-.345.327-.015-.019-.904-1.282-1.976-2.808L6.365 1.85H1.8zm1.782.91 8.078 11.294c.772 1.08 1.413 1.973 1.425 1.984.016.017.241.02 1.05.017l1.03-.004-2.694-3.766L7.796 5.75 5.722 2.852l-1.039-.004-1.039-.004z" clip-rule="evenodd"/>
+  </symbol>
+</svg>
diff --git a/rustfmt.toml b/rustfmt.toml
new file mode 100644
index 0000000..6a8e4c3
--- /dev/null
+++ b/rustfmt.toml
@@ -0,0 +1,18 @@
+# Rustfmt configuration
+edition = "2024"
+max_width = 80
+hard_tabs = false
+tab_spaces = 4
+newline_style = "Unix"
+use_small_heuristics = "Default"
+reorder_imports = true
+reorder_modules = true
+remove_nested_parens = true
+merge_derives = true
+use_try_shorthand = false
+use_field_init_shorthand = false
+force_explicit_abi = true
+imports_granularity = "Crate"
+group_imports = "StdExternalCrate"
+format_macro_bodies = true
+format_macro_matchers = true
\ No newline at end of file
diff --git a/src/App.css b/src/App.css
new file mode 100644
index 0000000..f90339d
--- /dev/null
+++ b/src/App.css
@@ -0,0 +1,184 @@
+.counter {
+  font-size: 16px;
+  padding: 5px 10px;
+  border-radius: 5px;
+  color: var(--accent);
+  background: var(--accent-bg);
+  border: 2px solid transparent;
+  transition: border-color 0.3s;
+  margin-bottom: 24px;
+
+  &:hover {
+    border-color: var(--accent-border);
+  }
+  &:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+  }
+}
+
+.hero {
+  position: relative;
+
+  .base,
+  .framework,
+  .vite {
+    inset-inline: 0;
+    margin: 0 auto;
+  }
+
+  .base {
+    width: 170px;
+    position: relative;
+    z-index: 0;
+  }
+
+  .framework,
+  .vite {
+    position: absolute;
+  }
+
+  .framework {
+    z-index: 1;
+    top: 34px;
+    height: 28px;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(44deg) rotateY(39deg)
+      scale(1.4);
+  }
+
+  .vite {
+    z-index: 0;
+    top: 107px;
+    height: 26px;
+    width: auto;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(40deg) rotateY(39deg)
+      scale(0.8);
+  }
+}
+
+#center {
+  display: flex;
+  flex-direction: column;
+  gap: 25px;
+  place-content: center;
+  place-items: center;
+  flex-grow: 1;
+
+  @media (max-width: 1024px) {
+    padding: 32px 20px 24px;
+    gap: 18px;
+  }
+}
+
+#next-steps {
+  display: flex;
+  border-top: 1px solid var(--border);
+  text-align: left;
+
+  & > div {
+    flex: 1 1 0;
+    padding: 32px;
+    @media (max-width: 1024px) {
+      padding: 24px 20px;
+    }
+  }
+
+  .icon {
+    margin-bottom: 16px;
+    width: 22px;
+    height: 22px;
+  }
+
+  @media (max-width: 1024px) {
+    flex-direction: column;
+    text-align: center;
+  }
+}
+
+#docs {
+  border-right: 1px solid var(--border);
+
+  @media (max-width: 1024px) {
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+  }
+}
+
+#next-steps ul {
+  list-style: none;
+  padding: 0;
+  display: flex;
+  gap: 8px;
+  margin: 32px 0 0;
+
+  .logo {
+    height: 18px;
+  }
+
+  a {
+    color: var(--text-h);
+    font-size: 16px;
+    border-radius: 6px;
+    background: var(--social-bg);
+    display: flex;
+    padding: 6px 12px;
+    align-items: center;
+    gap: 8px;
+    text-decoration: none;
+    transition: box-shadow 0.3s;
+
+    &:hover {
+      box-shadow: var(--shadow);
+    }
+    .button-icon {
+      height: 18px;
+      width: 18px;
+    }
+  }
+
+  @media (max-width: 1024px) {
+    margin-top: 20px;
+    flex-wrap: wrap;
+    justify-content: center;
+
+    li {
+      flex: 1 1 calc(50% - 8px);
+    }
+
+    a {
+      width: 100%;
+      justify-content: center;
+      box-sizing: border-box;
+    }
+  }
+}
+
+#spacer {
+  height: 88px;
+  border-top: 1px solid var(--border);
+  @media (max-width: 1024px) {
+    height: 48px;
+  }
+}
+
+.ticks {
+  position: relative;
+  width: 100%;
+
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    top: -4.5px;
+    border: 5px solid transparent;
+  }
+
+  &::before {
+    left: 0;
+    border-left-color: var(--border);
+  }
+  &::after {
+    right: 0;
+    border-right-color: var(--border);
+  }
+}
diff --git a/src/assets/hero.png b/src/assets/hero.png
new file mode 100644
index 0000000..02251f4
Binary files /dev/null and b/src/assets/hero.png differ
diff --git a/src/assets/vite.svg b/src/assets/vite.svg
new file mode 100644
index 0000000..5101b67
--- /dev/null
+++ b/src/assets/vite.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="77" height="47" fill="none" aria-labelledby="vite-logo-title" viewBox="0 0 77 47"><title id="vite-logo-title">Vite</title><style>.parenthesis{fill:#000}@media (prefers-color-scheme:dark){.parenthesis{fill:#fff}}</style><path fill="#9135ff" d="M40.151 45.71c-.663.844-2.02.374-2.02-.699V34.708a2.26 2.26 0 0 0-2.262-2.262H24.493c-.92 0-1.457-1.04-.92-1.788l7.479-10.471c1.07-1.498 0-3.578-1.842-3.578H15.443c-.92 0-1.456-1.04-.92-1.788l9.696-13.576c.213-.297.556-.474.92-.474h28.894c.92 0 1.456 1.04.92 1.788l-7.48 10.472c-1.07 1.497 0 3.578 1.842 3.578h11.376c.944 0 1.474 1.087.89 1.83L40.153 45.712z"/><mask id="a" width="48" height="47" x="14" y="0" maskUnits="userSpaceOnUse" style="mask-type:alpha"><path fill="#000" d="M40.047 45.71c-.663.843-2.02.374-2.02-.699V34.708a2.26 2.26 0 0 0-2.262-2.262H24.389c-.92 0-1.457-1.04-.92-1.788l7.479-10.472c1.07-1.497 0-3.578-1.842-3.578H15.34c-.92 0-1.456-1.04-.92-1.788l9.696-13.575c.213-.297.556-.474.92-.474H53.93c.92 0 1.456 1.04.92 1.788L47.37 13.03c-1.07 1.498 0 3.578 1.842 3.578h11.376c.944 0 1.474 1.088.89 1.831L40.049 45.712z"/></mask><g mask="url(#a)"><g filter="url(#b)"><ellipse cx="5.508" cy="14.704" fill="#eee6ff" rx="5.508" ry="14.704" transform="rotate(269.814 20.96 11.29)scale(-1 1)"/></g><g filter="url(#c)"><ellipse cx="10.399" cy="29.851" fill="#eee6ff" rx="10.399" ry="29.851" transform="rotate(89.814 -16.902 -8.275)scale(1 -1)"/></g><g filter="url(#d)"><ellipse cx="5.508" cy="30.487" fill="#8900ff" rx="5.508" ry="30.487" transform="rotate(89.814 -19.197 -7.127)scale(1 -1)"/></g><g filter="url(#e)"><ellipse cx="5.508" cy="30.599" fill="#8900ff" rx="5.508" ry="30.599" transform="rotate(89.814 -25.928 4.177)scale(1 -1)"/></g><g filter="url(#f)"><ellipse cx="5.508" cy="30.599" fill="#8900ff" rx="5.508" ry="30.599" transform="rotate(89.814 -25.738 5.52)scale(1 -1)"/></g><g filter="url(#g)"><ellipse cx="14.072" cy="22.078" fill="#eee6ff" rx="14.072" ry="22.078" transform="rotate(93.35 31.245 55.578)scale(-1 1)"/></g><g filter="url(#h)"><ellipse cx="3.47" cy="21.501" fill="#8900ff" rx="3.47" ry="21.501" transform="rotate(89.009 35.419 55.202)scale(-1 1)"/></g><g filter="url(#i)"><ellipse cx="3.47" cy="21.501" fill="#8900ff" rx="3.47" ry="21.501" transform="rotate(89.009 35.419 55.202)scale(-1 1)"/></g><g filter="url(#j)"><ellipse cx="14.592" cy="9.743" fill="#8900ff" rx="4.407" ry="29.108" transform="rotate(39.51 14.592 9.743)"/></g><g filter="url(#k)"><ellipse cx="61.728" cy="-5.321" fill="#8900ff" rx="4.407" ry="29.108" transform="rotate(37.892 61.728 -5.32)"/></g><g filter="url(#l)"><ellipse cx="55.618" cy="7.104" fill="#00c2ff" rx="5.971" ry="9.665" transform="rotate(37.892 55.618 7.104)"/></g><g filter="url(#m)"><ellipse cx="12.326" cy="39.103" fill="#8900ff" rx="4.407" ry="29.108" transform="rotate(37.892 12.326 39.103)"/></g><g filter="url(#n)"><ellipse cx="12.326" cy="39.103" fill="#8900ff" rx="4.407" ry="29.108" transform="rotate(37.892 12.326 39.103)"/></g><g filter="url(#o)"><ellipse cx="49.857" cy="30.678" fill="#8900ff" rx="4.407" ry="29.108" transform="rotate(37.892 49.857 30.678)"/></g><g filter="url(#p)"><ellipse cx="52.623" cy="33.171" fill="#00c2ff" rx="5.971" ry="15.297" transform="rotate(37.892 52.623 33.17)"/></g></g><path d="M6.919 0c-9.198 13.166-9.252 33.575 0 46.789h6.215c-9.25-13.214-9.196-33.623 0-46.789zm62.424 0h-6.215c9.198 13.166 9.252 33.575 0 46.789h6.215c9.25-13.214 9.196-33.623 0-46.789" class="parenthesis"/><defs><filter id="b" width="60.045" height="41.654" x="-5.564" y="16.92" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="7.659"/></filter><filter id="c" width="90.34" height="51.437" x="-40.407" y="-6.762" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="7.659"/></filter><filter id="d" width="79.355" height="29.4" x="-35.435" y="2.801" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="e" width="79.579" height="29.4" x="-30.84" y="20.8" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="f" width="79.579" height="29.4" x="-29.307" y="21.949" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="g" width="74.749" height="58.852" x="29.961" y="-17.13" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="7.659"/></filter><filter id="h" width="61.377" height="25.362" x="37.754" y="3.055" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="i" width="61.377" height="25.362" x="37.754" y="3.055" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="j" width="56.045" height="63.649" x="-13.43" y="-22.082" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="k" width="54.814" height="64.646" x="34.321" y="-37.644" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="l" width="33.541" height="35.313" x="38.847" y="-10.552" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="m" width="54.814" height="64.646" x="-15.081" y="6.78" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="n" width="54.814" height="64.646" x="-15.081" y="6.78" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="o" width="54.814" height="64.646" x="22.45" y="-1.645" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter><filter id="p" width="39.409" height="43.623" x="32.919" y="11.36" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"/><feBlend in="SourceGraphic" in2="BackgroundImageFix" result="shape"/><feGaussianBlur result="effect1_foregroundBlur_2002_17286" stdDeviation="4.596"/></filter></defs></svg>
diff --git a/src/client/endpoints.ts b/src/client/endpoints.ts
new file mode 100644
index 0000000..94c627a
--- /dev/null
+++ b/src/client/endpoints.ts
@@ -0,0 +1,3293 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import * as axios from 'axios';
+import type {
+  AxiosInstance,
+  AxiosRequestConfig,
+  AxiosResponse
+} from 'axios';
+
+import type {
+  AccessRequest,
+  AddIssueLabel,
+  AddPrLabel,
+  AddPrReaction,
+  AddReaction,
+  AddWorkspaceMember,
+  AgentListAllConversationsParams,
+  AgentListMessagesParams,
+  AgentRunRequest,
+  AgentRunResponse,
+  AgentSessionResponse,
+  AiAddRequest,
+  AiDiscussionResponse,
+  AiLikeResponse,
+  AiListDiscussionsParams,
+  AiListModelsParams,
+  AiModelCardResponse,
+  AiModelListItem,
+  AiModelResponse,
+  AiModelVersionResponse,
+  AiProviderResponse,
+  AppNotificationItem,
+  AssignIssueUser,
+  AssignPrUser,
+  AuthCaptchaParams,
+  AvatarUploadResponse,
+  BanCreateRequest,
+  BindIssuePullRequest,
+  BindIssueRepo,
+  BlameFileResponseDto,
+  BlobInfoResponse,
+  BlobUploadBody,
+  BlobUploadResponseDto,
+  BranchAheadBehindResponseDto,
+  BranchInfoResponseDto,
+  BranchListResponseDto,
+  BranchUpstreamResponseDto,
+  CaptchaResponse,
+  CategoryCreateRequest,
+  CategoryUpdateRequest,
+  ChannelListMessagesParams,
+  ChannelMessagesAroundParams,
+  ChannelMissedMessagesParams,
+  ChannelSearchParams,
+  CherryPickResponseDto,
+  CloneRepo,
+  CombinedCommitStatus,
+  CommitHistoryResponseDto,
+  CommitInfoResponseDto,
+  CommitStatusResponse,
+  CompareResponse,
+  ContentResponse,
+  ContextMe,
+  ContributionHeatmapResponse,
+  ContributorDto,
+  ConversationResponse,
+  ConversationWithSessionResponse,
+  CreateAgentSession,
+  CreateComment,
+  CreateCommitStatus,
+  CreateContent,
+  CreateConversation,
+  CreateFork,
+  CreateIssue,
+  CreateLabel,
+  CreateMessageRequest,
+  CreateMilestone,
+  CreatePrComment,
+  CreatePrReview,
+  CreatePrReviewComment,
+  CreateProtect,
+  CreatePullRequest,
+  CreateRelease,
+  CreateRepo,
+  CreateUserAccessToken,
+  CreateUserSshKey,
+  CreateWebhook,
+  CreateWorkspace,
+  CreateWorkspaceGroup,
+  CreateWorkspaceJoinApply,
+  CreatedUserAccessToken,
+  CustomStatusRequest,
+  DiffResultDto,
+  Disable2FAParams,
+  DismissPrReview,
+  DndRequest,
+  DraftSaveRequest,
+  EmailChangeRequest,
+  EmailResponse,
+  EmailVerifyRequest,
+  Enable2FAResponse,
+  ForkResponse,
+  Get2FAStatusResponse,
+  GitAheadBehindParams,
+  GitArchiveParams,
+  GitBlameFileParams,
+  GitBlobInfoParams,
+  GitCherryPickBody,
+  GitCommitHistoryParams,
+  GitCommitWalkBody,
+  GitDeleteBranchParams,
+  GitDeleteContentsParams,
+  GitDiffBranchesParams,
+  GitDiffParams,
+  GitForkBranchBody,
+  GitGetContentsParams,
+  GitInitTagBody,
+  GitListBranchesParams,
+  GitListCommitsParams,
+  GitListContributorsParams,
+  GitListDeliveriesParams,
+  GitListForksParams,
+  GitListProtectsParams,
+  GitListRefsParams,
+  GitListReposParams,
+  GitListTagsParams,
+  GitListWebhooksParams,
+  GitRefResponse,
+  GitTreeEntriesParams,
+  GitTreeEntryByPathFromCommitParams,
+  GitTreeEntryByPathParams,
+  GitUpdateTagBody,
+  GitWatchRepoBody,
+  InviteAcceptRequest,
+  InviteCreateRequest,
+  IssueAuthor,
+  IssueCommentResponse,
+  IssueEventResponse,
+  IssuePullRequestResponse,
+  IssueReactionResponse,
+  IssueRepoResponse,
+  IssueResponse,
+  IssuesListIssuesParams,
+  LabelResponse,
+  LanguageStatDto,
+  LoginParams,
+  MergePullRequest,
+  MessageResponse,
+  MilestoneResponse,
+  NotificationMarkAllReadRequest,
+  PinRequest,
+  PresenceUpdateRequest,
+  ProtectResponse,
+  PublicUserResponse,
+  PullRequestCommentResponse,
+  PullRequestListPrsParams,
+  PullRequestReactionResponse,
+  PullRequestResponse,
+  PullRequestReviewCommentResponse,
+  PullRequestReviewResponse,
+  ReactionRequest,
+  ReadReceiptRequest,
+  ReadmeDto,
+  RegisterParams,
+  ReleaseResponse,
+  RenameBranchBody,
+  RepoResponse,
+  ResetPasswordRequest,
+  ResetPasswordVerifyParams,
+  RoomCreateRequest,
+  RoomUpdateRequest,
+  RsaResponse,
+  ScreenShareRequest,
+  SearchParams,
+  SearchResponse,
+  SetIssueMilestone,
+  TagInfoResponseDto,
+  TagInitResponseDto,
+  TagSummaryResponseDto,
+  ThreadCreateRequest,
+  TokenRequest,
+  TokenResponse,
+  TransferRepo,
+  TreeEntriesResponseDto,
+  TreeEntryByPathResponseDto,
+  TypingRequest,
+  UpdateAgentSession,
+  UpdateComment,
+  UpdateContent,
+  UpdateConversation,
+  UpdateIssue,
+  UpdateLabel,
+  UpdateMessageRequest,
+  UpdateMilestone,
+  UpdatePrComment,
+  UpdateProtect,
+  UpdatePullRequest,
+  UpdateRelease,
+  UpdateRepo,
+  UpdateUserAccessToken,
+  UpdateUserAccessibilityConfig,
+  UpdateUserAppearanceConfig,
+  UpdateUserNotificationConfig,
+  UpdateUserPrivacyConfig,
+  UpdateUserProfileConfig,
+  UpdateUserSshKey,
+  UpdateWebhook,
+  UpdateWorkspace,
+  UpdateWorkspaceGroup,
+  UpdateWorkspaceJoinStrategy,
+  UpdateWorkspaceMember,
+  UserAccessToken,
+  UserAccessibilityConfig,
+  UserAppearanceConfig,
+  UserConfigResponse,
+  UserContributionHeatmapParams,
+  UserNotificationConfig,
+  UserPrivacyConfig,
+  UserProfileConfig,
+  UserRelationCard,
+  UserRelationCounts,
+  UserRelationStatus,
+  UserSshKey,
+  UserSummaryResponse,
+  UsersFollowersParams,
+  UsersFollowingParams,
+  UsersUserChpcParams,
+  Verify2FAParams,
+  VoiceDeafRequest,
+  VoiceMuteRequest,
+  WebhookDeliveryResponse,
+  WebhookResponse,
+  WorkspaceGroupResponse,
+  WorkspaceJoinApplyResponse,
+  WorkspaceJoinApprovalResponse,
+  WorkspaceJoinStrategyResponse,
+  WorkspaceListJoinAppliesParams,
+  WorkspaceListMembersParams,
+  WorkspaceMemberResponse,
+  WorkspaceResponse
+} from './models';
+
+export const getGitDataAIAPI = (axiosInstance: AxiosInstance = axios.default) => {
+const agentListAllConversations = (
+    params?: AgentListAllConversationsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ConversationWithSessionResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/agent/conversations`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const agentGetConversation = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ConversationResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/agent/conversations/${id}`,options
+    );
+  }
+
+const agentDeleteConversation = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/agent/conversations/${id}`,options
+    );
+  }
+
+const agentUpdateConversation = (
+    id: string,
+    updateConversation: UpdateConversation, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ConversationResponse>> => {
+    return axiosInstance.patch(
+      `/api/v1/agent/conversations/${id}`,
+      updateConversation,options
+    );
+  }
+
+const agentListMessages = (
+    id: string,
+    params?: AgentListMessagesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<MessageResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/agent/conversations/${id}/messages`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const agentSendMessage = (
+    id: string,
+    agentRunRequest: AgentRunRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AgentRunResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/agent/conversations/${id}/messages`,
+      agentRunRequest,options
+    );
+  }
+
+const agentStreamAgent = (
+    id: string,
+    agentRunRequest: AgentRunRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/agent/conversations/${id}/stream`,
+      agentRunRequest,options
+    );
+  }
+
+const agentListSessions = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AgentSessionResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/agent/sessions`,options
+    );
+  }
+
+const agentCreateSession = (
+    createAgentSession: CreateAgentSession, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AgentSessionResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/agent/sessions`,
+      createAgentSession,options
+    );
+  }
+
+const agentGetSession = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AgentSessionResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/agent/sessions/${id}`,options
+    );
+  }
+
+const agentDeleteSession = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/agent/sessions/${id}`,options
+    );
+  }
+
+const agentUpdateSession = (
+    id: string,
+    updateAgentSession: UpdateAgentSession, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AgentSessionResponse>> => {
+    return axiosInstance.patch(
+      `/api/v1/agent/sessions/${id}`,
+      updateAgentSession,options
+    );
+  }
+
+const agentListConversations = (
+    sessionId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ConversationResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/agent/sessions/${sessionId}/conversations`,options
+    );
+  }
+
+const agentCreateConversation = (
+    sessionId: string,
+    createConversation: CreateConversation, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ConversationResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/agent/sessions/${sessionId}/conversations`,
+      createConversation,options
+    );
+  }
+
+const aiListModels = (
+    params?: AiListModelsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiModelListItem[]>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const aiGetModel = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiModelResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models/${id}`,options
+    );
+  }
+
+const aiGetCard = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<null | AiModelCardResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models/${id}/card`,options
+    );
+  }
+
+const aiListDiscussions = (
+    id: string,
+    params?: AiListDiscussionsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiDiscussionResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models/${id}/discussions`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const aiListLikes = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiLikeResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models/${id}/likes`,options
+    );
+  }
+
+const aiListTags = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<string[]>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models/${id}/tags`,options
+    );
+  }
+
+const aiListVersions = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiModelVersionResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/models/${id}/versions`,options
+    );
+  }
+
+const aiListProviders = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiProviderResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/providers`,options
+    );
+  }
+
+const aiGetProvider = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AiProviderResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/ai/providers/${id}`,options
+    );
+  }
+
+const authStatus2fa = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<Get2FAStatusResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/auth/2fa`,options
+    );
+  }
+
+const authDisable2fa = (
+    disable2FAParams: Disable2FAParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/auth/2fa`,{data: disable2FAParams,...options}
+    );
+  }
+
+const authRegenerateBackupCodes = (
+    authRegenerateBackupCodesBody: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/2fa/backup-codes`,
+      authRegenerateBackupCodesBody,options
+    );
+  }
+
+const authEnable2fa = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<Enable2FAResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/2fa/enable`,
+      undefined,options
+    );
+  }
+
+const authVerify2fa = (
+    verify2FAParams: Verify2FAParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/2fa/verify`,
+      verify2FAParams,options
+    );
+  }
+
+const authCaptcha = (
+    params: AuthCaptchaParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CaptchaResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/auth/captcha`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const authGetEmail = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<EmailResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/auth/email`,options
+    );
+  }
+
+const authEmailChangeRequest = (
+    emailChangeRequest: EmailChangeRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/email`,
+      emailChangeRequest,options
+    );
+  }
+
+const authEmailVerify = (
+    emailVerifyRequest: EmailVerifyRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/email/verify`,
+      emailVerifyRequest,options
+    );
+  }
+
+const authLogin = (
+    loginParams: LoginParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/login`,
+      loginParams,options
+    );
+  }
+
+const authLogout = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/logout`,
+      undefined,options
+    );
+  }
+
+const authMe = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContextMe>> => {
+    return axiosInstance.get(
+      `/api/v1/auth/me`,options
+    );
+  }
+
+const authRsa = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<RsaResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/auth/public-key`,options
+    );
+  }
+
+const authRegister = (
+    registerParams: RegisterParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/register`,
+      registerParams,options
+    );
+  }
+
+const authResetPasswordRequest = (
+    resetPasswordRequest: ResetPasswordRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/reset-password/request`,
+      resetPasswordRequest,options
+    );
+  }
+
+const authResetPasswordVerify = (
+    resetPasswordVerifyParams: ResetPasswordVerifyParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/auth/reset-password/verify`,
+      resetPasswordVerifyParams,options
+    );
+  }
+
+const search = (
+    params?: SearchParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<SearchResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/search`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const userListAccessTokens = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserAccessToken[]>> => {
+    return axiosInstance.get(
+      `/api/v1/user/access-tokens`,options
+    );
+  }
+
+const userCreateAccessToken = (
+    createUserAccessToken: CreateUserAccessToken, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CreatedUserAccessToken>> => {
+    return axiosInstance.post(
+      `/api/v1/user/access-tokens`,
+      createUserAccessToken,options
+    );
+  }
+
+const userUpdateAccessToken = (
+    id: number,
+    updateUserAccessToken: UpdateUserAccessToken, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserAccessToken>> => {
+    return axiosInstance.put(
+      `/api/v1/user/access-tokens/${id}`,
+      updateUserAccessToken,options
+    );
+  }
+
+const userRevokeAccessToken = (
+    id: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/user/access-tokens/${id}`,options
+    );
+  }
+
+const userUploadAvatar = (
+    userUploadAvatarBody: Blob, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AvatarUploadResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/user/avatar`,
+      userUploadAvatarBody,options
+    );
+  }
+
+const userConfig = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserConfigResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/user/config`,options
+    );
+  }
+
+const userListNotifications = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AppNotificationItem[]>> => {
+    return axiosInstance.get(
+      `/api/v1/user/notifications`,options
+    );
+  }
+
+const userUpdateAccessibility = (
+    updateUserAccessibilityConfig: UpdateUserAccessibilityConfig, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserAccessibilityConfig>> => {
+    return axiosInstance.put(
+      `/api/v1/user/config/accessibility`,
+      updateUserAccessibilityConfig,options
+    );
+  }
+
+const userUpdateAppearance = (
+    updateUserAppearanceConfig: UpdateUserAppearanceConfig, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserAppearanceConfig>> => {
+    return axiosInstance.put(
+      `/api/v1/user/config/appearance`,
+      updateUserAppearanceConfig,options
+    );
+  }
+
+const userUpdateNotification = (
+    updateUserNotificationConfig: UpdateUserNotificationConfig, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserNotificationConfig>> => {
+    return axiosInstance.put(
+      `/api/v1/user/config/notification`,
+      updateUserNotificationConfig,options
+    );
+  }
+
+const userUpdatePrivacy = (
+    updateUserPrivacyConfig: UpdateUserPrivacyConfig, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserPrivacyConfig>> => {
+    return axiosInstance.put(
+      `/api/v1/user/config/privacy`,
+      updateUserPrivacyConfig,options
+    );
+  }
+
+const userUpdateProfile = (
+    updateUserProfileConfig: UpdateUserProfileConfig, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserProfileConfig>> => {
+    return axiosInstance.put(
+      `/api/v1/user/config/profile`,
+      updateUserProfileConfig,options
+    );
+  }
+
+const userContributionHeatmap = (
+    params?: UserContributionHeatmapParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContributionHeatmapResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/user/contribution-heatmap`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const userInvalidateChpcCache = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/user/contribution-heatmap/cache`,options
+    );
+  }
+
+const userListSshKeys = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserSshKey[]>> => {
+    return axiosInstance.get(
+      `/api/v1/user/ssh-keys`,options
+    );
+  }
+
+const userAddSshKey = (
+    createUserSshKey: CreateUserSshKey, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserSshKey>> => {
+    return axiosInstance.post(
+      `/api/v1/user/ssh-keys`,
+      createUserSshKey,options
+    );
+  }
+
+const userUpdateSshKey = (
+    id: number,
+    updateUserSshKey: UpdateUserSshKey, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserSshKey>> => {
+    return axiosInstance.put(
+      `/api/v1/user/ssh-keys/${id}`,
+      updateUserSshKey,options
+    );
+  }
+
+const userRevokeSshKey = (
+    id: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/user/ssh-keys/${id}`,options
+    );
+  }
+
+const usersUserAvatar = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<unknown>> => {
+    return axiosInstance.get(
+      `/api/v1/users/avatar/${username}`,options
+    );
+  }
+
+const usersBlockedList = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationCard[]>> => {
+    return axiosInstance.get(
+      `/api/v1/users/blocked`,options
+    );
+  }
+
+const usersBlockUser = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationStatus>> => {
+    return axiosInstance.post(
+      `/api/v1/users/${username}/block`,
+      undefined,options
+    );
+  }
+
+const usersUserChpc = (
+    username: string,
+    params?: UsersUserChpcParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContributionHeatmapResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/contribution-heatmap`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const usersFollowUser = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationStatus>> => {
+    return axiosInstance.post(
+      `/api/v1/users/${username}/follow`,
+      undefined,options
+    );
+  }
+
+const usersFollowers = (
+    username: string,
+    params?: UsersFollowersParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationCard[]>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/followers`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const usersFollowing = (
+    username: string,
+    params?: UsersFollowingParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationCard[]>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/following`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const usersUserPublic = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PublicUserResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/public`,options
+    );
+  }
+
+const usersRelationStatus = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationStatus>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/relation`,options
+    );
+  }
+
+const usersRelationCounts = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationCounts>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/relation-counts`,options
+    );
+  }
+
+const usersUserSummary = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserSummaryResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/users/${username}/summary`,options
+    );
+  }
+
+const usersUnblockUser = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationStatus>> => {
+    return axiosInstance.post(
+      `/api/v1/users/${username}/unblock`,
+      undefined,options
+    );
+  }
+
+const usersUnfollowUser = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<UserRelationStatus>> => {
+    return axiosInstance.post(
+      `/api/v1/users/${username}/unfollow`,
+      undefined,options
+    );
+  }
+
+const workspaceCreateWorkspace = (
+    createWorkspace: CreateWorkspace, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace`,
+      createWorkspace,options
+    );
+  }
+
+const workspaceMyJoinApplies = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinApplyResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/join/my-applies`,options
+    );
+  }
+
+const workspaceMyWorkspaces = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/my`,options
+    );
+  }
+
+const workspaceGetWorkspace = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}`,options
+    );
+  }
+
+const workspaceUpdateWorkspace = (
+    wk: string,
+    updateWorkspace: UpdateWorkspace, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}`,
+      updateWorkspace,options
+    );
+  }
+
+const workspaceGetAvatar = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<unknown>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/avatar`,options
+    );
+  }
+
+const workspaceUploadAvatar = (
+    wk: string,
+    workspaceUploadAvatarBody: Blob, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<AvatarUploadResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/avatar`,
+      workspaceUploadAvatarBody,options
+    );
+  }
+
+const workspaceListGroups = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceGroupResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/groups`,options
+    );
+  }
+
+const workspaceCreateGroup = (
+    wk: string,
+    createWorkspaceGroup: CreateWorkspaceGroup, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceGroupResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/groups`,
+      createWorkspaceGroup,options
+    );
+  }
+
+const workspaceUpdateGroup = (
+    wk: string,
+    groupName: string,
+    updateWorkspaceGroup: UpdateWorkspaceGroup, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceGroupResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/groups/${groupName}`,
+      updateWorkspaceGroup,options
+    );
+  }
+
+const workspaceDeleteGroup = (
+    wk: string,
+    groupName: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/groups/${groupName}`,options
+    );
+  }
+
+const workspaceListGroupMembers = (
+    wk: string,
+    groupName: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceMemberResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/groups/${groupName}/members`,options
+    );
+  }
+
+const workspaceAddGroupMember = (
+    wk: string,
+    groupName: string,
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/groups/${groupName}/members/${username}`,
+      undefined,options
+    );
+  }
+
+const workspaceRemoveGroupMember = (
+    wk: string,
+    groupName: string,
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/groups/${groupName}/members/${username}`,options
+    );
+  }
+
+const issuesListIssues = (
+    wk: string,
+    params?: IssuesListIssuesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/issues`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const issuesCreateIssue = (
+    wk: string,
+    createIssue: CreateIssue, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues`,
+      createIssue,options
+    );
+  }
+
+const issuesGetIssue = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/issues/${number}`,options
+    );
+  }
+
+const issuesUpdateIssue = (
+    wk: string,
+    number: number,
+    updateIssue: UpdateIssue, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/issues/${number}`,
+      updateIssue,options
+    );
+  }
+
+const issuesDeleteIssue = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}`,options
+    );
+  }
+
+const issuesAssignUser = (
+    wk: string,
+    number: number,
+    assignIssueUser: AssignIssueUser, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueAuthor[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/assignees`,
+      assignIssueUser,options
+    );
+  }
+
+const issuesUnassignUser = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueAuthor[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/assignees`,options
+    );
+  }
+
+const issuesCloseIssue = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/close`,
+      undefined,options
+    );
+  }
+
+const issuesListComments = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueCommentResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/issues/${number}/comments`,options
+    );
+  }
+
+const issuesCreateComment = (
+    wk: string,
+    number: number,
+    createComment: CreateComment, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueCommentResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/comments`,
+      createComment,options
+    );
+  }
+
+const issuesUpdateComment = (
+    wk: string,
+    number: number,
+    commentId: string,
+    updateComment: UpdateComment, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueCommentResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/issues/${number}/comments/${commentId}`,
+      updateComment,options
+    );
+  }
+
+const issuesDeleteComment = (
+    wk: string,
+    number: number,
+    commentId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/comments/${commentId}`,options
+    );
+  }
+
+const issuesAddCommentReaction = (
+    wk: string,
+    number: number,
+    commentId: string,
+    addReaction: AddReaction, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueReactionResponse[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/comments/${commentId}/reactions`,
+      addReaction,options
+    );
+  }
+
+const issuesRemoveCommentReaction = (
+    wk: string,
+    number: number,
+    commentId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueReactionResponse[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/comments/${commentId}/reactions`,options
+    );
+  }
+
+const issuesListEvents = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueEventResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/issues/${number}/events`,options
+    );
+  }
+
+const issuesAddIssueLabel = (
+    wk: string,
+    number: number,
+    addIssueLabel: AddIssueLabel, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/labels`,
+      addIssueLabel,options
+    );
+  }
+
+const issuesRemoveIssueLabel = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/labels`,options
+    );
+  }
+
+const issuesSetIssueMilestone = (
+    wk: string,
+    number: number,
+    setIssueMilestone: SetIssueMilestone, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<null | MilestoneResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/milestone`,
+      setIssueMilestone,options
+    );
+  }
+
+const issuesClearIssueMilestone = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/milestone`,options
+    );
+  }
+
+const issuesBindPullRequest = (
+    wk: string,
+    number: number,
+    bindIssuePullRequest: BindIssuePullRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssuePullRequestResponse[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/pull-requests`,
+      bindIssuePullRequest,options
+    );
+  }
+
+const issuesUnbindPullRequest = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssuePullRequestResponse[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/pull-requests`,options
+    );
+  }
+
+const issuesAddReaction = (
+    wk: string,
+    number: number,
+    addReaction: AddReaction, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueReactionResponse[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/reactions`,
+      addReaction,options
+    );
+  }
+
+const issuesRemoveReaction = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueReactionResponse[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/reactions`,options
+    );
+  }
+
+const issuesReopenIssue = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/reopen`,
+      undefined,options
+    );
+  }
+
+const issuesBindRepo = (
+    wk: string,
+    number: number,
+    bindIssueRepo: BindIssueRepo, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueRepoResponse[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/issues/${number}/repos`,
+      bindIssueRepo,options
+    );
+  }
+
+const issuesUnbindRepo = (
+    wk: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueRepoResponse[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/issues/${number}/repos`,options
+    );
+  }
+
+const workspaceJoinStrategy = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinStrategyResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/join-strategy`,options
+    );
+  }
+
+const workspaceUpdateJoinStrategy = (
+    wk: string,
+    updateWorkspaceJoinStrategy: UpdateWorkspaceJoinStrategy, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinStrategyResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/join-strategy`,
+      updateWorkspaceJoinStrategy,options
+    );
+  }
+
+const workspaceListJoinApplies = (
+    wk: string,
+    params?: WorkspaceListJoinAppliesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinApplyResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/join/applies`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const workspaceApproveJoin = (
+    wk: string,
+    username: string,
+    approveWorkspaceJoinApply: ApproveWorkspaceJoinApply, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinApprovalResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/join/applies/${username}/approve`,
+      approveWorkspaceJoinApply,options
+    );
+  }
+
+const workspaceApplyJoin = (
+    wk: string,
+    createWorkspaceJoinApply: CreateWorkspaceJoinApply, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinApplyResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/join/apply`,
+      createWorkspaceJoinApply,options
+    );
+  }
+
+const workspaceCancelJoin = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceJoinApplyResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/join/cancel`,
+      undefined,options
+    );
+  }
+
+const issuesListLabels = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/labels`,options
+    );
+  }
+
+const issuesCreateLabel = (
+    wk: string,
+    createLabel: CreateLabel, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/labels`,
+      createLabel,options
+    );
+  }
+
+const issuesUpdateLabel = (
+    wk: string,
+    labelId: string,
+    updateLabel: UpdateLabel, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/labels/${labelId}`,
+      updateLabel,options
+    );
+  }
+
+const issuesDeleteLabel = (
+    wk: string,
+    labelId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/labels/${labelId}`,options
+    );
+  }
+
+const workspaceListMembers = (
+    wk: string,
+    params?: WorkspaceListMembersParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceMemberResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/members`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const workspaceAddMember = (
+    wk: string,
+    addWorkspaceMember: AddWorkspaceMember, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceMemberResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/members`,
+      addWorkspaceMember,options
+    );
+  }
+
+const workspaceUpdateMember = (
+    wk: string,
+    username: string,
+    updateWorkspaceMember: UpdateWorkspaceMember, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WorkspaceMemberResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/members/${username}`,
+      updateWorkspaceMember,options
+    );
+  }
+
+const workspaceRemoveMember = (
+    wk: string,
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/members/${username}`,options
+    );
+  }
+
+const issuesListMilestones = (
+    wk: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<MilestoneResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/milestones`,options
+    );
+  }
+
+const issuesCreateMilestone = (
+    wk: string,
+    createMilestone: CreateMilestone, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<MilestoneResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/milestones`,
+      createMilestone,options
+    );
+  }
+
+const issuesUpdateMilestone = (
+    wk: string,
+    milestoneId: string,
+    updateMilestone: UpdateMilestone, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<MilestoneResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/milestones/${milestoneId}`,
+      updateMilestone,options
+    );
+  }
+
+const issuesDeleteMilestone = (
+    wk: string,
+    milestoneId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/milestones/${milestoneId}`,options
+    );
+  }
+
+const gitListRepos = (
+    wk: string,
+    params?: GitListReposParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<RepoResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitCreateRepo = (
+    wk: string,
+    createRepo: CreateRepo, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos`,
+      createRepo,options
+    );
+  }
+
+const gitCloneRepo = (
+    wk: string,
+    cloneRepo: CloneRepo, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/clone`,
+      cloneRepo,options
+    );
+  }
+
+const gitGetRepo = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<RepoResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}`,options
+    );
+  }
+
+const gitUpdateRepo = (
+    wk: string,
+    repo: string,
+    updateRepo: UpdateRepo, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<RepoResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/repos/${repo}`,
+      updateRepo,options
+    );
+  }
+
+const gitDeleteRepo = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}`,options
+    );
+  }
+
+const gitArchiveRepo = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<RepoResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/archive`,
+      undefined,options
+    );
+  }
+
+const gitCombinedStatus = (
+    wk: string,
+    repo: string,
+    sha: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CombinedCommitStatus>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/commits/${sha}/status`,options
+    );
+  }
+
+const gitListStatuses = (
+    wk: string,
+    repo: string,
+    sha: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CommitStatusResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/commits/${sha}/statuses`,options
+    );
+  }
+
+const gitCompare = (
+    wk: string,
+    repo: string,
+    basehead: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CompareResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/compare/${basehead}`,options
+    );
+  }
+
+const gitGetContents = (
+    wk: string,
+    repo: string,
+    path: string,
+    params?: GitGetContentsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContentResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/contents/${path}`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitUpdateContents = (
+    wk: string,
+    repo: string,
+    path: string,
+    updateContent: UpdateContent, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContentResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/repos/${repo}/contents/${path}`,
+      updateContent,options
+    );
+  }
+
+const gitCreateContents = (
+    wk: string,
+    repo: string,
+    path: string,
+    createContent: CreateContent, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContentResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/contents/${path}`,
+      createContent,options
+    );
+  }
+
+const gitDeleteContents = (
+    wk: string,
+    repo: string,
+    path: string,
+    params: GitDeleteContentsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/contents/${path}`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitListForks = (
+    wk: string,
+    repo: string,
+    params?: GitListForksParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ForkResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/forks`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitCreateFork = (
+    wk: string,
+    repo: string,
+    createFork: CreateFork, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ForkResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/forks`,
+      createFork,options
+    );
+  }
+
+const gitArchive = (
+    wk: string,
+    repo: string,
+    params?: GitArchiveParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/archive`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitBlameFile = (
+    wk: string,
+    repo: string,
+    params: GitBlameFileParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BlameFileResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/blame`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitBlobUpload = (
+    wk: string,
+    repo: string,
+    blobUploadBody: BlobUploadBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BlobUploadResponseDto>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/blobs`,
+      blobUploadBody,options
+    );
+  }
+
+const gitBlobInfo = (
+    wk: string,
+    repo: string,
+    oid: string,
+    params?: GitBlobInfoParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BlobInfoResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/blobs/${oid}`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitListBranches = (
+    wk: string,
+    repo: string,
+    params?: GitListBranchesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BranchListResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+/**
+ * BranchForkParams { name, oid, force }
+ */
+const gitForkBranch = (
+    wk: string,
+    repo: string,
+    gitForkBranchBody: GitForkBranchBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches`,
+      gitForkBranchBody,options
+    );
+  }
+
+const gitBranchInfo = (
+    wk: string,
+    repo: string,
+    name: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BranchInfoResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches/${name}`,options
+    );
+  }
+
+const gitDeleteBranch = (
+    wk: string,
+    repo: string,
+    name: string,
+    params?: GitDeleteBranchParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches/${name}`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitRenameBranch = (
+    wk: string,
+    repo: string,
+    name: string,
+    renameBranchBody: RenameBranchBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches/${name}`,
+      renameBranchBody,options
+    );
+  }
+
+const gitAheadBehind = (
+    wk: string,
+    repo: string,
+    name: string,
+    params: GitAheadBehindParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BranchAheadBehindResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches/${name}/ahead-behind`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitBranchUpstream = (
+    wk: string,
+    repo: string,
+    name: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<BranchUpstreamResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/branches/${name}/upstream`,options
+    );
+  }
+
+const gitListCommits = (
+    wk: string,
+    repo: string,
+    params?: GitListCommitsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CommitHistoryResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/commits`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+/**
+ * CommitCherryPickParams
+ */
+const gitCherryPick = (
+    wk: string,
+    repo: string,
+    gitCherryPickBody: GitCherryPickBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CherryPickResponseDto>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/commits/cherry-pick`,
+      gitCherryPickBody,options
+    );
+  }
+
+const gitCommitHistory = (
+    wk: string,
+    repo: string,
+    params?: GitCommitHistoryParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CommitHistoryResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/commits/history`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+/**
+ * CommitWalkParams
+ */
+const gitCommitWalk = (
+    wk: string,
+    repo: string,
+    gitCommitWalkBody: GitCommitWalkBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CommitHistoryResponseDto>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/commits/walk`,
+      gitCommitWalkBody,options
+    );
+  }
+
+const gitCommitInfo = (
+    wk: string,
+    repo: string,
+    oid: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CommitInfoResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/commits/${oid}`,options
+    );
+  }
+
+const gitTreeEntryByPathFromCommit = (
+    wk: string,
+    repo: string,
+    oid: string,
+    params: GitTreeEntryByPathFromCommitParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TreeEntryByPathResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/commits/${oid}/tree`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitListContributors = (
+    wk: string,
+    repo: string,
+    params?: GitListContributorsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ContributorDto[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/contributors`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitDiff = (
+    wk: string,
+    repo: string,
+    params?: GitDiffParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/diff`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitDiffBranches = (
+    wk: string,
+    repo: string,
+    params: GitDiffBranchesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<DiffResultDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/diff/branches`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitGetLanguages = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LanguageStatDto[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/languages`,options
+    );
+  }
+
+const gitGetReadme = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<null | ReadmeDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/readme`,options
+    );
+  }
+
+const gitListRefs = (
+    wk: string,
+    repo: string,
+    params?: GitListRefsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<GitRefResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/refs`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitStarStatus = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/star`,options
+    );
+  }
+
+const gitStarRepo = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/star`,
+      undefined,options
+    );
+  }
+
+const gitUnstarRepo = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/star`,options
+    );
+  }
+
+const gitListTags = (
+    wk: string,
+    repo: string,
+    params?: GitListTagsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TagSummaryResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/tags`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+/**
+ * TagInitParams { name, oid, message, tagger, force }
+ */
+const gitInitTag = (
+    wk: string,
+    repo: string,
+    gitInitTagBody: GitInitTagBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TagInitResponseDto>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/tags`,
+      gitInitTagBody,options
+    );
+  }
+
+const gitTagInfo = (
+    wk: string,
+    repo: string,
+    name: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TagInfoResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/tags/${name}`,options
+    );
+  }
+
+const gitDeleteTag = (
+    wk: string,
+    repo: string,
+    name: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/tags/${name}`,options
+    );
+  }
+
+const gitUpdateTag = (
+    wk: string,
+    repo: string,
+    name: string,
+    gitUpdateTagBody: GitUpdateTagBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/tags/${name}`,
+      gitUpdateTagBody,options
+    );
+  }
+
+const gitTreeEntries = (
+    wk: string,
+    repo: string,
+    oid: string,
+    params?: GitTreeEntriesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TreeEntriesResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/trees/${oid}`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitTreeEntryByPath = (
+    wk: string,
+    repo: string,
+    treeOid: string,
+    params: GitTreeEntryByPathParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TreeEntryByPathResponseDto>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/trees/${treeOid}/entries`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitWatchStatus = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/watch`,options
+    );
+  }
+
+/**
+ * WatchLevel {level: String}
+ */
+const gitWatchRepo = (
+    wk: string,
+    repo: string,
+    gitWatchRepoBody: GitWatchRepoBody, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/watch`,
+      gitWatchRepoBody,options
+    );
+  }
+
+const gitUnwatchRepo = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/git/watch`,options
+    );
+  }
+
+const gitListProtects = (
+    wk: string,
+    repo: string,
+    params?: GitListProtectsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ProtectResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/protect`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitCreateProtect = (
+    wk: string,
+    repo: string,
+    createProtect: CreateProtect, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ProtectResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/protect`,
+      createProtect,options
+    );
+  }
+
+const gitUpdateProtect = (
+    wk: string,
+    repo: string,
+    protectId: string,
+    updateProtect: UpdateProtect, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ProtectResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/repos/${repo}/protect/${protectId}`,
+      updateProtect,options
+    );
+  }
+
+const gitDeleteProtect = (
+    wk: string,
+    repo: string,
+    protectId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/protect/${protectId}`,options
+    );
+  }
+
+const pullRequestListPrs = (
+    wk: string,
+    repo: string,
+    params?: PullRequestListPrsParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const pullRequestCreatePr = (
+    wk: string,
+    repo: string,
+    createPullRequest: CreatePullRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests`,
+      createPullRequest,options
+    );
+  }
+
+const pullRequestGetPr = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}`,options
+    );
+  }
+
+const pullRequestDeletePr = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}`,options
+    );
+  }
+
+const pullRequestUpdatePr = (
+    wk: string,
+    repo: string,
+    number: number,
+    updatePullRequest: UpdatePullRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestResponse>> => {
+    return axiosInstance.patch(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}`,
+      updatePullRequest,options
+    );
+  }
+
+const pullRequestAssignUser = (
+    wk: string,
+    repo: string,
+    number: number,
+    assignPrUser: AssignPrUser, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueAuthor[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/assignees`,
+      assignPrUser,options
+    );
+  }
+
+const pullRequestUnassignUser = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<IssueAuthor[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/assignees`,options
+    );
+  }
+
+const pullRequestListComments = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestCommentResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/comments`,options
+    );
+  }
+
+const pullRequestCreateComment = (
+    wk: string,
+    repo: string,
+    number: number,
+    createPrComment: CreatePrComment, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestCommentResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/comments`,
+      createPrComment,options
+    );
+  }
+
+const pullRequestUpdateComment = (
+    wk: string,
+    repo: string,
+    number: number,
+    commentId: string,
+    updatePrComment: UpdatePrComment, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestCommentResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/comments/${commentId}`,
+      updatePrComment,options
+    );
+  }
+
+const pullRequestDeleteComment = (
+    wk: string,
+    repo: string,
+    number: number,
+    commentId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/comments/${commentId}`,options
+    );
+  }
+
+const pullRequestAddCommentReaction = (
+    wk: string,
+    repo: string,
+    number: number,
+    commentId: string,
+    addPrReaction: AddPrReaction, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestReactionResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/comments/${commentId}/reactions`,
+      addPrReaction,options
+    );
+  }
+
+const pullRequestRemoveCommentReaction = (
+    wk: string,
+    repo: string,
+    number: number,
+    commentId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/comments/${commentId}/reactions`,options
+    );
+  }
+
+const pullRequestAddLabel = (
+    wk: string,
+    repo: string,
+    number: number,
+    addPrLabel: AddPrLabel, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse[]>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/labels`,
+      addPrLabel,options
+    );
+  }
+
+const pullRequestRemoveLabel = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<LabelResponse[]>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/labels`,options
+    );
+  }
+
+const pullRequestMergeAnalysis = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/merge`,options
+    );
+  }
+
+const pullRequestMergePr = (
+    wk: string,
+    repo: string,
+    number: number,
+    mergePullRequest: MergePullRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/merge`,
+      mergePullRequest,options
+    );
+  }
+
+const pullRequestAddReaction = (
+    wk: string,
+    repo: string,
+    number: number,
+    addPrReaction: AddPrReaction, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestReactionResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/reactions`,
+      addPrReaction,options
+    );
+  }
+
+const pullRequestRemoveReaction = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/reactions`,options
+    );
+  }
+
+const pullRequestCreateReviewComment = (
+    wk: string,
+    repo: string,
+    number: number,
+    createPrReviewComment: CreatePrReviewComment, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestReviewCommentResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/review-comments`,
+      createPrReviewComment,options
+    );
+  }
+
+const pullRequestListReviews = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestReviewResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/reviews`,options
+    );
+  }
+
+const pullRequestCreateReview = (
+    wk: string,
+    repo: string,
+    number: number,
+    createPrReview: CreatePrReview, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestReviewResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/reviews`,
+      createPrReview,options
+    );
+  }
+
+const pullRequestDismissReview = (
+    wk: string,
+    repo: string,
+    number: number,
+    reviewId: string,
+    dismissPrReview: DismissPrReview, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/reviews/${reviewId}/dismiss`,
+      dismissPrReview,options
+    );
+  }
+
+const pullRequestUpdateBranch = (
+    wk: string,
+    repo: string,
+    number: number, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<PullRequestResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/pull-requests/${number}/update-branch`,
+      undefined,options
+    );
+  }
+
+const gitListReleases = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ReleaseResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases`,options
+    );
+  }
+
+const gitCreateRelease = (
+    wk: string,
+    repo: string,
+    createRelease: CreateRelease, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ReleaseResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases`,
+      createRelease,options
+    );
+  }
+
+const gitGetReleaseByTag = (
+    wk: string,
+    repo: string,
+    tag: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ReleaseResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases/tags/${tag}`,options
+    );
+  }
+
+const gitDeleteReleaseByTag = (
+    wk: string,
+    repo: string,
+    tag: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases/tags/${tag}`,options
+    );
+  }
+
+const gitGetRelease = (
+    wk: string,
+    repo: string,
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ReleaseResponse>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases/${id}`,options
+    );
+  }
+
+const gitDeleteRelease = (
+    wk: string,
+    repo: string,
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases/${id}`,options
+    );
+  }
+
+const gitUpdateRelease = (
+    wk: string,
+    repo: string,
+    id: string,
+    updateRelease: UpdateRelease, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<ReleaseResponse>> => {
+    return axiosInstance.patch(
+      `/api/v1/workspace/${wk}/repos/${repo}/releases/${id}`,
+      updateRelease,options
+    );
+  }
+
+const gitCreateStatus = (
+    wk: string,
+    repo: string,
+    sha: string,
+    createCommitStatus: CreateCommitStatus, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<CommitStatusResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/statuses/${sha}`,
+      createCommitStatus,options
+    );
+  }
+
+const gitGetTopics = (
+    wk: string,
+    repo: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<string[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/topics`,options
+    );
+  }
+
+const gitUpdateTopics = (
+    wk: string,
+    repo: string,
+    gitUpdateTopicsBody: string[], options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<string[]>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/repos/${repo}/topics`,
+      gitUpdateTopicsBody,options
+    );
+  }
+
+const gitTransferRepo = (
+    wk: string,
+    repo: string,
+    transferRepo: TransferRepo, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<RepoResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/transfer`,
+      transferRepo,options
+    );
+  }
+
+const gitListWebhooks = (
+    wk: string,
+    repo: string,
+    params?: GitListWebhooksParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WebhookResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/webhooks`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const gitCreateWebhook = (
+    wk: string,
+    repo: string,
+    createWebhook: CreateWebhook, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WebhookResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/workspace/${wk}/repos/${repo}/webhooks`,
+      createWebhook,options
+    );
+  }
+
+const gitUpdateWebhook = (
+    wk: string,
+    repo: string,
+    webhookId: string,
+    updateWebhook: UpdateWebhook, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WebhookResponse>> => {
+    return axiosInstance.put(
+      `/api/v1/workspace/${wk}/repos/${repo}/webhooks/${webhookId}`,
+      updateWebhook,options
+    );
+  }
+
+const gitDeleteWebhook = (
+    wk: string,
+    repo: string,
+    webhookId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/workspace/${wk}/repos/${repo}/webhooks/${webhookId}`,options
+    );
+  }
+
+const gitListDeliveries = (
+    wk: string,
+    repo: string,
+    webhookId: string,
+    params?: GitListDeliveriesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<WebhookDeliveryResponse[]>> => {
+    return axiosInstance.get(
+      `/api/v1/workspace/${wk}/repos/${repo}/webhooks/${webhookId}/deliveries`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const channelCategoryDelete = (
+    categoryId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/categories/${categoryId}`,options
+    );
+  }
+
+const channelCategoryUpdate = (
+    categoryId: string,
+    categoryUpdateRequest: CategoryUpdateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/categories/${categoryId}`,
+      categoryUpdateRequest,options
+    );
+  }
+
+const channelCsrfToken = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/csrf`,options
+    );
+  }
+
+const channelCustomStatusUpdate = (
+    customStatusRequest: CustomStatusRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/custom-status`,
+      customStatusRequest,options
+    );
+  }
+
+const channelInviteCreate = (
+    inviteCreateRequest: InviteCreateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/invites`,
+      inviteCreateRequest,options
+    );
+  }
+
+const channelInviteAccept = (
+    inviteAcceptRequest: InviteAcceptRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/invites/accept`,
+      inviteAcceptRequest,options
+    );
+  }
+
+const channelInviteRevoke = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/invites/${id}`,options
+    );
+  }
+
+const channelRevokeMessage = (
+    messageId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/messages/${messageId}`,options
+    );
+  }
+
+const channelUpdateMessage = (
+    messageId: string,
+    updateMessageRequest: UpdateMessageRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/messages/${messageId}`,
+      updateMessageRequest,options
+    );
+  }
+
+const channelNotificationMarkAllRead = (
+    notificationMarkAllReadRequest: NotificationMarkAllReadRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/notifications/read-all`,
+      notificationMarkAllReadRequest,options
+    );
+  }
+
+const channelNotificationArchive = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/notifications/${id}`,options
+    );
+  }
+
+const channelNotificationMarkRead = (
+    id: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/notifications/${id}/read`,
+      undefined,options
+    );
+  }
+
+const channelPing = (
+     options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/ping`,options
+    );
+  }
+
+const channelPresenceUpdate = (
+    presenceUpdateRequest: PresenceUpdateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/presence`,
+      presenceUpdateRequest,options
+    );
+  }
+
+const channelRoomCreate = (
+    roomCreateRequest: RoomCreateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms`,
+      roomCreateRequest,options
+    );
+  }
+
+const channelRoomGet = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/rooms/${roomId}`,options
+    );
+  }
+
+const channelRoomDelete = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}`,options
+    );
+  }
+
+const channelRoomUpdate = (
+    roomId: string,
+    roomUpdateRequest: RoomUpdateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/rooms/${roomId}`,
+      roomUpdateRequest,options
+    );
+  }
+
+const channelAiList = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/rooms/${roomId}/ai`,options
+    );
+  }
+
+const channelAiAdd = (
+    roomId: string,
+    aiAddRequest: AiAddRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/ai`,
+      aiAddRequest,options
+    );
+  }
+
+const channelAiStop = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/ai/stop`,
+      undefined,options
+    );
+  }
+
+const channelAiRemove = (
+    roomId: string,
+    agentSessionId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}/ai/${agentSessionId}`,options
+    );
+  }
+
+const channelDndUpdate = (
+    roomId: string,
+    dndRequest: DndRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/rooms/${roomId}/dnd`,
+      dndRequest,options
+    );
+  }
+
+const channelDraftSave = (
+    roomId: string,
+    draftSaveRequest: DraftSaveRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.put(
+      `/api/v1/ws/rooms/${roomId}/drafts`,
+      draftSaveRequest,options
+    );
+  }
+
+const channelDraftClear = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}/drafts`,options
+    );
+  }
+
+const channelAccessGrant = (
+    roomId: string,
+    accessRequest: AccessRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/members`,
+      accessRequest,options
+    );
+  }
+
+const channelAccessRevoke = (
+    roomId: string,
+    userId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}/members/${userId}`,options
+    );
+  }
+
+const channelListMessages = (
+    roomId: string,
+    params?: ChannelListMessagesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/rooms/${roomId}/messages`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const channelCreateMessage = (
+    roomId: string,
+    createMessageRequest: CreateMessageRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/messages`,
+      createMessageRequest,options
+    );
+  }
+
+const channelMessagesAround = (
+    roomId: string,
+    params: ChannelMessagesAroundParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/rooms/${roomId}/messages/around`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const channelMissedMessages = (
+    roomId: string,
+    params: ChannelMissedMessagesParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/rooms/${roomId}/messages/missed`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const channelPinAdd = (
+    roomId: string,
+    pinRequest: PinRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/pins`,
+      pinRequest,options
+    );
+  }
+
+const channelPinRemove = (
+    roomId: string,
+    pinRequest: PinRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}/pins`,{data: pinRequest,...options}
+    );
+  }
+
+const channelReactionAdd = (
+    roomId: string,
+    reactionRequest: ReactionRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/reactions`,
+      reactionRequest,options
+    );
+  }
+
+const channelReactionRemove = (
+    roomId: string,
+    reactionRequest: ReactionRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}/reactions`,{data: reactionRequest,...options}
+    );
+  }
+
+const channelReadReceipt = (
+    roomId: string,
+    readReceiptRequest: ReadReceiptRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/read-receipt`,
+      readReceiptRequest,options
+    );
+  }
+
+const channelScreenShare = (
+    roomId: string,
+    screenShareRequest: ScreenShareRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/screen-share`,
+      screenShareRequest,options
+    );
+  }
+
+const channelSubscribe = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/subscribe`,
+      undefined,options
+    );
+  }
+
+const channelUnsubscribe = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/rooms/${roomId}/subscribe`,options
+    );
+  }
+
+const channelThreadCreate = (
+    roomId: string,
+    threadCreateRequest: ThreadCreateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/threads`,
+      threadCreateRequest,options
+    );
+  }
+
+const channelTyping = (
+    roomId: string,
+    typingRequest: TypingRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/typing`,
+      typingRequest,options
+    );
+  }
+
+const channelVoiceDeaf = (
+    roomId: string,
+    voiceDeafRequest: VoiceDeafRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/voice/deaf`,
+      voiceDeafRequest,options
+    );
+  }
+
+const channelVoiceJoin = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/voice/join`,
+      undefined,options
+    );
+  }
+
+const channelVoiceLeave = (
+    roomId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/voice/leave`,
+      undefined,options
+    );
+  }
+
+const channelVoiceMute = (
+    roomId: string,
+    voiceMuteRequest: VoiceMuteRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/rooms/${roomId}/voice/mute`,
+      voiceMuteRequest,options
+    );
+  }
+
+const channelSearch = (
+    params: ChannelSearchParams, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/search`,{
+    ...options,
+        params: {...params, ...options?.params},}
+    );
+  }
+
+const channelThreadArchive = (
+    threadId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/threads/${threadId}/archive`,
+      undefined,options
+    );
+  }
+
+const channelThreadResolve = (
+    threadId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.patch(
+      `/api/v1/ws/threads/${threadId}/resolve`,
+      undefined,options
+    );
+  }
+
+const channelGenerateToken = (
+    tokenRequest: TokenRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<TokenResponse>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/token`,
+      tokenRequest,options
+    );
+  }
+
+const channelUserSummary = (
+    username: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.get(
+      `/api/v1/ws/users/summary/${username}`,options
+    );
+  }
+
+const channelBanCreate = (
+    workspaceId: string,
+    banCreateRequest: BanCreateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/workspaces/${workspaceId}/bans`,
+      banCreateRequest,options
+    );
+  }
+
+const channelBanRemove = (
+    workspaceId: string,
+    userId: string, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.delete(
+      `/api/v1/ws/workspaces/${workspaceId}/bans/${userId}`,options
+    );
+  }
+
+const channelCategoryCreate = (
+    workspaceId: string,
+    categoryCreateRequest: CategoryCreateRequest, options?: AxiosRequestConfig
+ ): Promise<AxiosResponse<void>> => {
+    return axiosInstance.post(
+      `/api/v1/ws/workspaces/${workspaceId}/categories`,
+      categoryCreateRequest,options
+    );
+  }
+
+return {agentListAllConversations,agentGetConversation,agentDeleteConversation,agentUpdateConversation,agentListMessages,agentSendMessage,agentStreamAgent,agentListSessions,agentCreateSession,agentGetSession,agentDeleteSession,agentUpdateSession,agentListConversations,agentCreateConversation,aiListModels,aiGetModel,aiGetCard,aiListDiscussions,aiListLikes,aiListTags,aiListVersions,aiListProviders,aiGetProvider,authStatus2fa,authDisable2fa,authRegenerateBackupCodes,authEnable2fa,authVerify2fa,authCaptcha,authGetEmail,authEmailChangeRequest,authEmailVerify,authLogin,authLogout,authMe,authRsa,authRegister,authResetPasswordRequest,authResetPasswordVerify,search,userListAccessTokens,userCreateAccessToken,userUpdateAccessToken,userRevokeAccessToken,userUploadAvatar,userListNotifications,userConfig,userUpdateAccessibility,userUpdateAppearance,userUpdateNotification,userUpdatePrivacy,userUpdateProfile,userContributionHeatmap,userInvalidateChpcCache,userListSshKeys,userAddSshKey,userUpdateSshKey,userRevokeSshKey,usersUserAvatar,usersBlockedList,usersBlockUser,usersUserChpc,usersFollowUser,usersFollowers,usersFollowing,usersUserPublic,usersRelationStatus,usersRelationCounts,usersUserSummary,usersUnblockUser,usersUnfollowUser,workspaceCreateWorkspace,workspaceMyJoinApplies,workspaceMyWorkspaces,workspaceGetWorkspace,workspaceUpdateWorkspace,workspaceGetAvatar,workspaceUploadAvatar,workspaceListGroups,workspaceCreateGroup,workspaceUpdateGroup,workspaceDeleteGroup,workspaceListGroupMembers,workspaceAddGroupMember,workspaceRemoveGroupMember,issuesListIssues,issuesCreateIssue,issuesGetIssue,issuesUpdateIssue,issuesDeleteIssue,issuesAssignUser,issuesUnassignUser,issuesCloseIssue,issuesListComments,issuesCreateComment,issuesUpdateComment,issuesDeleteComment,issuesAddCommentReaction,issuesRemoveCommentReaction,issuesListEvents,issuesAddIssueLabel,issuesRemoveIssueLabel,issuesSetIssueMilestone,issuesClearIssueMilestone,issuesBindPullRequest,issuesUnbindPullRequest,issuesAddReaction,issuesRemoveReaction,issuesReopenIssue,issuesBindRepo,issuesUnbindRepo,workspaceJoinStrategy,workspaceUpdateJoinStrategy,workspaceListJoinApplies,workspaceApproveJoin,workspaceApplyJoin,workspaceCancelJoin,issuesListLabels,issuesCreateLabel,issuesUpdateLabel,issuesDeleteLabel,workspaceListMembers,workspaceAddMember,workspaceUpdateMember,workspaceRemoveMember,issuesListMilestones,issuesCreateMilestone,issuesUpdateMilestone,issuesDeleteMilestone,gitListRepos,gitCreateRepo,gitCloneRepo,gitGetRepo,gitUpdateRepo,gitDeleteRepo,gitArchiveRepo,gitCombinedStatus,gitListStatuses,gitCompare,gitGetContents,gitUpdateContents,gitCreateContents,gitDeleteContents,gitListForks,gitCreateFork,gitArchive,gitBlameFile,gitBlobUpload,gitBlobInfo,gitListBranches,gitForkBranch,gitBranchInfo,gitDeleteBranch,gitRenameBranch,gitAheadBehind,gitBranchUpstream,gitListCommits,gitCherryPick,gitCommitHistory,gitCommitWalk,gitCommitInfo,gitTreeEntryByPathFromCommit,gitListContributors,gitDiff,gitDiffBranches,gitGetLanguages,gitGetReadme,gitListRefs,gitStarStatus,gitStarRepo,gitUnstarRepo,gitListTags,gitInitTag,gitTagInfo,gitDeleteTag,gitUpdateTag,gitTreeEntries,gitTreeEntryByPath,gitWatchStatus,gitWatchRepo,gitUnwatchRepo,gitListProtects,gitCreateProtect,gitUpdateProtect,gitDeleteProtect,pullRequestListPrs,pullRequestCreatePr,pullRequestGetPr,pullRequestDeletePr,pullRequestUpdatePr,pullRequestAssignUser,pullRequestUnassignUser,pullRequestListComments,pullRequestCreateComment,pullRequestUpdateComment,pullRequestDeleteComment,pullRequestAddCommentReaction,pullRequestRemoveCommentReaction,pullRequestAddLabel,pullRequestRemoveLabel,pullRequestMergeAnalysis,pullRequestMergePr,pullRequestAddReaction,pullRequestRemoveReaction,pullRequestCreateReviewComment,pullRequestListReviews,pullRequestCreateReview,pullRequestDismissReview,pullRequestUpdateBranch,gitListReleases,gitCreateRelease,gitGetReleaseByTag,gitDeleteReleaseByTag,gitGetRelease,gitDeleteRelease,gitUpdateRelease,gitCreateStatus,gitGetTopics,gitUpdateTopics,gitTransferRepo,gitListWebhooks,gitCreateWebhook,gitUpdateWebhook,gitDeleteWebhook,gitListDeliveries,channelCategoryDelete,channelCategoryUpdate,channelCsrfToken,channelCustomStatusUpdate,channelInviteCreate,channelInviteAccept,channelInviteRevoke,channelRevokeMessage,channelUpdateMessage,channelNotificationMarkAllRead,channelNotificationArchive,channelNotificationMarkRead,channelPing,channelPresenceUpdate,channelRoomCreate,channelRoomGet,channelRoomDelete,channelRoomUpdate,channelAiList,channelAiAdd,channelAiStop,channelAiRemove,channelDndUpdate,channelDraftSave,channelDraftClear,channelAccessGrant,channelAccessRevoke,channelListMessages,channelCreateMessage,channelMessagesAround,channelMissedMessages,channelPinAdd,channelPinRemove,channelReactionAdd,channelReactionRemove,channelReadReceipt,channelScreenShare,channelSubscribe,channelUnsubscribe,channelThreadCreate,channelTyping,channelVoiceDeaf,channelVoiceJoin,channelVoiceLeave,channelVoiceMute,channelSearch,channelThreadArchive,channelThreadResolve,channelGenerateToken,channelUserSummary,channelBanCreate,channelBanRemove,channelCategoryCreate}};
+export type AgentListAllConversationsResult = AxiosResponse<ConversationWithSessionResponse[]>
+export type AgentGetConversationResult = AxiosResponse<ConversationResponse>
+export type AgentDeleteConversationResult = AxiosResponse<void>
+export type AgentUpdateConversationResult = AxiosResponse<ConversationResponse>
+export type AgentListMessagesResult = AxiosResponse<MessageResponse[]>
+export type AgentSendMessageResult = AxiosResponse<AgentRunResponse>
+export type AgentStreamAgentResult = AxiosResponse<void>
+export type AgentListSessionsResult = AxiosResponse<AgentSessionResponse[]>
+export type AgentCreateSessionResult = AxiosResponse<AgentSessionResponse>
+export type AgentGetSessionResult = AxiosResponse<AgentSessionResponse>
+export type AgentDeleteSessionResult = AxiosResponse<void>
+export type AgentUpdateSessionResult = AxiosResponse<AgentSessionResponse>
+export type AgentListConversationsResult = AxiosResponse<ConversationResponse[]>
+export type AgentCreateConversationResult = AxiosResponse<ConversationResponse>
+export type AiListModelsResult = AxiosResponse<AiModelListItem[]>
+export type AiGetModelResult = AxiosResponse<AiModelResponse>
+export type AiGetCardResult = AxiosResponse<null | AiModelCardResponse>
+export type AiListDiscussionsResult = AxiosResponse<AiDiscussionResponse[]>
+export type AiListLikesResult = AxiosResponse<AiLikeResponse[]>
+export type AiListTagsResult = AxiosResponse<string[]>
+export type AiListVersionsResult = AxiosResponse<AiModelVersionResponse[]>
+export type AiListProvidersResult = AxiosResponse<AiProviderResponse[]>
+export type AiGetProviderResult = AxiosResponse<AiProviderResponse>
+export type AuthStatus2faResult = AxiosResponse<Get2FAStatusResponse>
+export type AuthDisable2faResult = AxiosResponse<void>
+export type AuthRegenerateBackupCodesResult = AxiosResponse<void>
+export type AuthEnable2faResult = AxiosResponse<Enable2FAResponse>
+export type AuthVerify2faResult = AxiosResponse<void>
+export type AuthCaptchaResult = AxiosResponse<CaptchaResponse>
+export type AuthGetEmailResult = AxiosResponse<EmailResponse>
+export type AuthEmailChangeRequestResult = AxiosResponse<void>
+export type AuthEmailVerifyResult = AxiosResponse<void>
+export type AuthLoginResult = AxiosResponse<void>
+export type AuthLogoutResult = AxiosResponse<void>
+export type AuthMeResult = AxiosResponse<ContextMe>
+export type AuthRsaResult = AxiosResponse<RsaResponse>
+export type AuthRegisterResult = AxiosResponse<void>
+export type AuthResetPasswordRequestResult = AxiosResponse<void>
+export type AuthResetPasswordVerifyResult = AxiosResponse<void>
+export type SearchResult = AxiosResponse<SearchResponse>
+export type UserListAccessTokensResult = AxiosResponse<UserAccessToken[]>
+export type UserCreateAccessTokenResult = AxiosResponse<CreatedUserAccessToken>
+export type UserUpdateAccessTokenResult = AxiosResponse<UserAccessToken>
+export type UserRevokeAccessTokenResult = AxiosResponse<void>
+export type UserUploadAvatarResult = AxiosResponse<AvatarUploadResponse>
+export type UserConfigResult = AxiosResponse<UserConfigResponse>
+export type UserUpdateAccessibilityResult = AxiosResponse<UserAccessibilityConfig>
+export type UserUpdateAppearanceResult = AxiosResponse<UserAppearanceConfig>
+export type UserUpdateNotificationResult = AxiosResponse<UserNotificationConfig>
+export type UserUpdatePrivacyResult = AxiosResponse<UserPrivacyConfig>
+export type UserUpdateProfileResult = AxiosResponse<UserProfileConfig>
+export type UserContributionHeatmapResult = AxiosResponse<ContributionHeatmapResponse>
+export type UserInvalidateChpcCacheResult = AxiosResponse<void>
+export type UserListSshKeysResult = AxiosResponse<UserSshKey[]>
+export type UserAddSshKeyResult = AxiosResponse<UserSshKey>
+export type UserUpdateSshKeyResult = AxiosResponse<UserSshKey>
+export type UserRevokeSshKeyResult = AxiosResponse<void>
+export type UsersUserAvatarResult = AxiosResponse<unknown>
+export type UsersBlockedListResult = AxiosResponse<UserRelationCard[]>
+export type UsersBlockUserResult = AxiosResponse<UserRelationStatus>
+export type UsersUserChpcResult = AxiosResponse<ContributionHeatmapResponse>
+export type UsersFollowUserResult = AxiosResponse<UserRelationStatus>
+export type UsersFollowersResult = AxiosResponse<UserRelationCard[]>
+export type UsersFollowingResult = AxiosResponse<UserRelationCard[]>
+export type UsersUserPublicResult = AxiosResponse<PublicUserResponse>
+export type UsersRelationStatusResult = AxiosResponse<UserRelationStatus>
+export type UsersRelationCountsResult = AxiosResponse<UserRelationCounts>
+export type UsersUserSummaryResult = AxiosResponse<UserSummaryResponse>
+export type UsersUnblockUserResult = AxiosResponse<UserRelationStatus>
+export type UsersUnfollowUserResult = AxiosResponse<UserRelationStatus>
+export type WorkspaceCreateWorkspaceResult = AxiosResponse<WorkspaceResponse>
+export type WorkspaceMyJoinAppliesResult = AxiosResponse<WorkspaceJoinApplyResponse[]>
+export type WorkspaceMyWorkspacesResult = AxiosResponse<WorkspaceResponse[]>
+export type WorkspaceGetWorkspaceResult = AxiosResponse<WorkspaceResponse>
+export type WorkspaceUpdateWorkspaceResult = AxiosResponse<WorkspaceResponse>
+export type WorkspaceGetAvatarResult = AxiosResponse<unknown>
+export type WorkspaceUploadAvatarResult = AxiosResponse<AvatarUploadResponse>
+export type WorkspaceListGroupsResult = AxiosResponse<WorkspaceGroupResponse[]>
+export type WorkspaceCreateGroupResult = AxiosResponse<WorkspaceGroupResponse>
+export type WorkspaceUpdateGroupResult = AxiosResponse<WorkspaceGroupResponse>
+export type WorkspaceDeleteGroupResult = AxiosResponse<void>
+export type WorkspaceListGroupMembersResult = AxiosResponse<WorkspaceMemberResponse[]>
+export type WorkspaceAddGroupMemberResult = AxiosResponse<void>
+export type WorkspaceRemoveGroupMemberResult = AxiosResponse<void>
+export type IssuesListIssuesResult = AxiosResponse<IssueResponse[]>
+export type IssuesCreateIssueResult = AxiosResponse<IssueResponse>
+export type IssuesGetIssueResult = AxiosResponse<IssueResponse>
+export type IssuesUpdateIssueResult = AxiosResponse<IssueResponse>
+export type IssuesDeleteIssueResult = AxiosResponse<void>
+export type IssuesAssignUserResult = AxiosResponse<IssueAuthor[]>
+export type IssuesUnassignUserResult = AxiosResponse<IssueAuthor[]>
+export type IssuesCloseIssueResult = AxiosResponse<IssueResponse>
+export type IssuesListCommentsResult = AxiosResponse<IssueCommentResponse[]>
+export type IssuesCreateCommentResult = AxiosResponse<IssueCommentResponse>
+export type IssuesUpdateCommentResult = AxiosResponse<IssueCommentResponse>
+export type IssuesDeleteCommentResult = AxiosResponse<void>
+export type IssuesAddCommentReactionResult = AxiosResponse<IssueReactionResponse[]>
+export type IssuesRemoveCommentReactionResult = AxiosResponse<IssueReactionResponse[]>
+export type IssuesListEventsResult = AxiosResponse<IssueEventResponse[]>
+export type IssuesAddIssueLabelResult = AxiosResponse<LabelResponse[]>
+export type IssuesRemoveIssueLabelResult = AxiosResponse<LabelResponse[]>
+export type IssuesSetIssueMilestoneResult = AxiosResponse<null | MilestoneResponse>
+export type IssuesClearIssueMilestoneResult = AxiosResponse<void>
+export type IssuesBindPullRequestResult = AxiosResponse<IssuePullRequestResponse[]>
+export type IssuesUnbindPullRequestResult = AxiosResponse<IssuePullRequestResponse[]>
+export type IssuesAddReactionResult = AxiosResponse<IssueReactionResponse[]>
+export type IssuesRemoveReactionResult = AxiosResponse<IssueReactionResponse[]>
+export type IssuesReopenIssueResult = AxiosResponse<IssueResponse>
+export type IssuesBindRepoResult = AxiosResponse<IssueRepoResponse[]>
+export type IssuesUnbindRepoResult = AxiosResponse<IssueRepoResponse[]>
+export type WorkspaceJoinStrategyResult = AxiosResponse<WorkspaceJoinStrategyResponse>
+export type WorkspaceUpdateJoinStrategyResult = AxiosResponse<WorkspaceJoinStrategyResponse>
+export type WorkspaceListJoinAppliesResult = AxiosResponse<WorkspaceJoinApplyResponse[]>
+export type WorkspaceApproveJoinResult = AxiosResponse<WorkspaceJoinApprovalResponse>
+export type WorkspaceApplyJoinResult = AxiosResponse<WorkspaceJoinApplyResponse>
+export type WorkspaceCancelJoinResult = AxiosResponse<WorkspaceJoinApplyResponse>
+export type IssuesListLabelsResult = AxiosResponse<LabelResponse[]>
+export type IssuesCreateLabelResult = AxiosResponse<LabelResponse>
+export type IssuesUpdateLabelResult = AxiosResponse<LabelResponse>
+export type IssuesDeleteLabelResult = AxiosResponse<void>
+export type WorkspaceListMembersResult = AxiosResponse<WorkspaceMemberResponse[]>
+export type WorkspaceAddMemberResult = AxiosResponse<WorkspaceMemberResponse>
+export type WorkspaceUpdateMemberResult = AxiosResponse<WorkspaceMemberResponse>
+export type WorkspaceRemoveMemberResult = AxiosResponse<void>
+export type IssuesListMilestonesResult = AxiosResponse<MilestoneResponse[]>
+export type IssuesCreateMilestoneResult = AxiosResponse<MilestoneResponse>
+export type IssuesUpdateMilestoneResult = AxiosResponse<MilestoneResponse>
+export type IssuesDeleteMilestoneResult = AxiosResponse<void>
+export type GitListReposResult = AxiosResponse<RepoResponse[]>
+export type GitCreateRepoResult = AxiosResponse<void>
+export type GitCloneRepoResult = AxiosResponse<void>
+export type GitGetRepoResult = AxiosResponse<RepoResponse>
+export type GitUpdateRepoResult = AxiosResponse<RepoResponse>
+export type GitDeleteRepoResult = AxiosResponse<void>
+export type GitArchiveRepoResult = AxiosResponse<RepoResponse>
+export type GitCombinedStatusResult = AxiosResponse<CombinedCommitStatus>
+export type GitListStatusesResult = AxiosResponse<CommitStatusResponse[]>
+export type GitCompareResult = AxiosResponse<CompareResponse>
+export type GitGetContentsResult = AxiosResponse<ContentResponse>
+export type GitUpdateContentsResult = AxiosResponse<ContentResponse>
+export type GitCreateContentsResult = AxiosResponse<ContentResponse>
+export type GitDeleteContentsResult = AxiosResponse<void>
+export type GitListForksResult = AxiosResponse<ForkResponse[]>
+export type GitCreateForkResult = AxiosResponse<ForkResponse>
+export type GitArchiveResult = AxiosResponse<void>
+export type GitBlameFileResult = AxiosResponse<BlameFileResponseDto>
+export type GitBlobUploadResult = AxiosResponse<BlobUploadResponseDto>
+export type GitBlobInfoResult = AxiosResponse<BlobInfoResponse>
+export type GitListBranchesResult = AxiosResponse<BranchListResponseDto>
+export type GitForkBranchResult = AxiosResponse<void>
+export type GitBranchInfoResult = AxiosResponse<BranchInfoResponseDto>
+export type GitDeleteBranchResult = AxiosResponse<void>
+export type GitRenameBranchResult = AxiosResponse<void>
+export type GitAheadBehindResult = AxiosResponse<BranchAheadBehindResponseDto>
+export type GitBranchUpstreamResult = AxiosResponse<BranchUpstreamResponseDto>
+export type GitListCommitsResult = AxiosResponse<CommitHistoryResponseDto>
+export type GitCherryPickResult = AxiosResponse<CherryPickResponseDto>
+export type GitCommitHistoryResult = AxiosResponse<CommitHistoryResponseDto>
+export type GitCommitWalkResult = AxiosResponse<CommitHistoryResponseDto>
+export type GitCommitInfoResult = AxiosResponse<CommitInfoResponseDto>
+export type GitTreeEntryByPathFromCommitResult = AxiosResponse<TreeEntryByPathResponseDto>
+export type GitListContributorsResult = AxiosResponse<ContributorDto[]>
+export type GitDiffResult = AxiosResponse<void>
+export type GitDiffBranchesResult = AxiosResponse<DiffResultDto>
+export type GitGetLanguagesResult = AxiosResponse<LanguageStatDto[]>
+export type GitGetReadmeResult = AxiosResponse<null | ReadmeDto>
+export type GitListRefsResult = AxiosResponse<GitRefResponse[]>
+export type GitStarStatusResult = AxiosResponse<void>
+export type GitStarRepoResult = AxiosResponse<void>
+export type GitUnstarRepoResult = AxiosResponse<void>
+export type GitListTagsResult = AxiosResponse<TagSummaryResponseDto>
+export type GitInitTagResult = AxiosResponse<TagInitResponseDto>
+export type GitTagInfoResult = AxiosResponse<TagInfoResponseDto>
+export type GitDeleteTagResult = AxiosResponse<void>
+export type GitUpdateTagResult = AxiosResponse<void>
+export type GitTreeEntriesResult = AxiosResponse<TreeEntriesResponseDto>
+export type GitTreeEntryByPathResult = AxiosResponse<TreeEntryByPathResponseDto>
+export type GitWatchStatusResult = AxiosResponse<void>
+export type GitWatchRepoResult = AxiosResponse<void>
+export type GitUnwatchRepoResult = AxiosResponse<void>
+export type GitListProtectsResult = AxiosResponse<ProtectResponse[]>
+export type GitCreateProtectResult = AxiosResponse<ProtectResponse>
+export type GitUpdateProtectResult = AxiosResponse<ProtectResponse>
+export type GitDeleteProtectResult = AxiosResponse<void>
+export type PullRequestListPrsResult = AxiosResponse<PullRequestResponse[]>
+export type PullRequestCreatePrResult = AxiosResponse<PullRequestResponse>
+export type PullRequestGetPrResult = AxiosResponse<PullRequestResponse>
+export type PullRequestDeletePrResult = AxiosResponse<void>
+export type PullRequestUpdatePrResult = AxiosResponse<PullRequestResponse>
+export type PullRequestAssignUserResult = AxiosResponse<IssueAuthor[]>
+export type PullRequestUnassignUserResult = AxiosResponse<IssueAuthor[]>
+export type PullRequestListCommentsResult = AxiosResponse<PullRequestCommentResponse[]>
+export type PullRequestCreateCommentResult = AxiosResponse<PullRequestCommentResponse>
+export type PullRequestUpdateCommentResult = AxiosResponse<PullRequestCommentResponse>
+export type PullRequestDeleteCommentResult = AxiosResponse<void>
+export type PullRequestAddCommentReactionResult = AxiosResponse<PullRequestReactionResponse>
+export type PullRequestRemoveCommentReactionResult = AxiosResponse<void>
+export type PullRequestAddLabelResult = AxiosResponse<LabelResponse[]>
+export type PullRequestRemoveLabelResult = AxiosResponse<LabelResponse[]>
+export type PullRequestMergeAnalysisResult = AxiosResponse<void>
+export type PullRequestMergePrResult = AxiosResponse<PullRequestResponse>
+export type PullRequestAddReactionResult = AxiosResponse<PullRequestReactionResponse>
+export type PullRequestRemoveReactionResult = AxiosResponse<void>
+export type PullRequestCreateReviewCommentResult = AxiosResponse<PullRequestReviewCommentResponse>
+export type PullRequestListReviewsResult = AxiosResponse<PullRequestReviewResponse[]>
+export type PullRequestCreateReviewResult = AxiosResponse<PullRequestReviewResponse>
+export type PullRequestDismissReviewResult = AxiosResponse<void>
+export type PullRequestUpdateBranchResult = AxiosResponse<PullRequestResponse>
+export type GitListReleasesResult = AxiosResponse<ReleaseResponse[]>
+export type GitCreateReleaseResult = AxiosResponse<ReleaseResponse>
+export type GitGetReleaseByTagResult = AxiosResponse<ReleaseResponse>
+export type GitDeleteReleaseByTagResult = AxiosResponse<void>
+export type GitGetReleaseResult = AxiosResponse<ReleaseResponse>
+export type GitDeleteReleaseResult = AxiosResponse<void>
+export type GitUpdateReleaseResult = AxiosResponse<ReleaseResponse>
+export type GitCreateStatusResult = AxiosResponse<CommitStatusResponse>
+export type GitGetTopicsResult = AxiosResponse<string[]>
+export type GitUpdateTopicsResult = AxiosResponse<string[]>
+export type GitTransferRepoResult = AxiosResponse<RepoResponse>
+export type GitListWebhooksResult = AxiosResponse<WebhookResponse[]>
+export type GitCreateWebhookResult = AxiosResponse<WebhookResponse>
+export type GitUpdateWebhookResult = AxiosResponse<WebhookResponse>
+export type GitDeleteWebhookResult = AxiosResponse<void>
+export type GitListDeliveriesResult = AxiosResponse<WebhookDeliveryResponse[]>
+export type ChannelCategoryDeleteResult = AxiosResponse<void>
+export type ChannelCategoryUpdateResult = AxiosResponse<void>
+export type ChannelCsrfTokenResult = AxiosResponse<void>
+export type ChannelCustomStatusUpdateResult = AxiosResponse<void>
+export type ChannelInviteCreateResult = AxiosResponse<void>
+export type ChannelInviteAcceptResult = AxiosResponse<void>
+export type ChannelInviteRevokeResult = AxiosResponse<void>
+export type ChannelRevokeMessageResult = AxiosResponse<void>
+export type ChannelUpdateMessageResult = AxiosResponse<void>
+export type ChannelNotificationMarkAllReadResult = AxiosResponse<void>
+export type ChannelNotificationArchiveResult = AxiosResponse<void>
+export type ChannelNotificationMarkReadResult = AxiosResponse<void>
+export type ChannelPingResult = AxiosResponse<void>
+export type ChannelPresenceUpdateResult = AxiosResponse<void>
+export type ChannelRoomCreateResult = AxiosResponse<void>
+export type ChannelRoomGetResult = AxiosResponse<void>
+export type ChannelRoomDeleteResult = AxiosResponse<void>
+export type ChannelRoomUpdateResult = AxiosResponse<void>
+export type ChannelAiListResult = AxiosResponse<void>
+export type ChannelAiAddResult = AxiosResponse<void>
+export type ChannelAiStopResult = AxiosResponse<void>
+export type ChannelAiRemoveResult = AxiosResponse<void>
+export type ChannelDndUpdateResult = AxiosResponse<void>
+export type ChannelDraftSaveResult = AxiosResponse<void>
+export type ChannelDraftClearResult = AxiosResponse<void>
+export type ChannelAccessGrantResult = AxiosResponse<void>
+export type ChannelAccessRevokeResult = AxiosResponse<void>
+export type ChannelListMessagesResult = AxiosResponse<void>
+export type ChannelCreateMessageResult = AxiosResponse<void>
+export type ChannelMessagesAroundResult = AxiosResponse<void>
+export type ChannelMissedMessagesResult = AxiosResponse<void>
+export type ChannelPinAddResult = AxiosResponse<void>
+export type ChannelPinRemoveResult = AxiosResponse<void>
+export type ChannelReactionAddResult = AxiosResponse<void>
+export type ChannelReactionRemoveResult = AxiosResponse<void>
+export type ChannelReadReceiptResult = AxiosResponse<void>
+export type ChannelScreenShareResult = AxiosResponse<void>
+export type ChannelSubscribeResult = AxiosResponse<void>
+export type ChannelUnsubscribeResult = AxiosResponse<void>
+export type ChannelThreadCreateResult = AxiosResponse<void>
+export type ChannelTypingResult = AxiosResponse<void>
+export type ChannelVoiceDeafResult = AxiosResponse<void>
+export type ChannelVoiceJoinResult = AxiosResponse<void>
+export type ChannelVoiceLeaveResult = AxiosResponse<void>
+export type ChannelVoiceMuteResult = AxiosResponse<void>
+export type ChannelSearchResult = AxiosResponse<void>
+export type ChannelThreadArchiveResult = AxiosResponse<void>
+export type ChannelThreadResolveResult = AxiosResponse<void>
+export type ChannelGenerateTokenResult = AxiosResponse<TokenResponse>
+export type ChannelUserSummaryResult = AxiosResponse<void>
+export type ChannelBanCreateResult = AxiosResponse<void>
+export type ChannelBanRemoveResult = AxiosResponse<void>
+export type ChannelCategoryCreateResult = AxiosResponse<void>
diff --git a/src/client/index.ts b/src/client/index.ts
new file mode 100644
index 0000000..6f60b10
--- /dev/null
+++ b/src/client/index.ts
@@ -0,0 +1,7 @@
+import axios from "axios";
+import { getGitDataAIAPI } from "./endpoints";
+
+export const api = axios.create({ baseURL: "", withCredentials: true, headers: { "Content-Type": "application/json" } });
+export const client = getGitDataAIAPI(api);
+export * from "./models";
+export type * from "./endpoints";
diff --git a/src/client/models/accessRequest.ts b/src/client/models/accessRequest.ts
new file mode 100644
index 0000000..7992525
--- /dev/null
+++ b/src/client/models/accessRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AccessRequest {
+  user: string;
+}
diff --git a/src/client/models/addIssueLabel.ts b/src/client/models/addIssueLabel.ts
new file mode 100644
index 0000000..e9e8271
--- /dev/null
+++ b/src/client/models/addIssueLabel.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AddIssueLabel {
+  label_id: string;
+}
diff --git a/src/client/models/addPrLabel.ts b/src/client/models/addPrLabel.ts
new file mode 100644
index 0000000..b5f5b7c
--- /dev/null
+++ b/src/client/models/addPrLabel.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AddPrLabel {
+  label_id: string;
+}
diff --git a/src/client/models/addPrReaction.ts b/src/client/models/addPrReaction.ts
new file mode 100644
index 0000000..5b28689
--- /dev/null
+++ b/src/client/models/addPrReaction.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AddPrReaction {
+  reaction: string;
+}
diff --git a/src/client/models/addReaction.ts b/src/client/models/addReaction.ts
new file mode 100644
index 0000000..4f46f7c
--- /dev/null
+++ b/src/client/models/addReaction.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AddReaction {
+  reaction: string;
+}
diff --git a/src/client/models/addWorkspaceMember.ts b/src/client/models/addWorkspaceMember.ts
new file mode 100644
index 0000000..22225d2
--- /dev/null
+++ b/src/client/models/addWorkspaceMember.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AddWorkspaceMember {
+  /** @nullable */
+  admin?: boolean | null;
+  username: string;
+}
diff --git a/src/client/models/agentCostInfo.ts b/src/client/models/agentCostInfo.ts
new file mode 100644
index 0000000..c57a160
--- /dev/null
+++ b/src/client/models/agentCostInfo.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AgentCostInfo {
+  amount: string;
+  currency: string;
+}
diff --git a/src/client/models/agentListAllConversationsParams.ts b/src/client/models/agentListAllConversationsParams.ts
new file mode 100644
index 0000000..7597adc
--- /dev/null
+++ b/src/client/models/agentListAllConversationsParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type AgentListAllConversationsParams = {
+/**
+ * Filter by workspace name
+ */
+wk?: string;
+};
diff --git a/src/client/models/agentListMessagesParams.ts b/src/client/models/agentListMessagesParams.ts
new file mode 100644
index 0000000..d419c35
--- /dev/null
+++ b/src/client/models/agentListMessagesParams.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type AgentListMessagesParams = {
+before?: string;
+/**
+ * @minimum 0
+ */
+limit?: number;
+};
diff --git a/src/client/models/agentRunRequest.ts b/src/client/models/agentRunRequest.ts
new file mode 100644
index 0000000..2e95c07
--- /dev/null
+++ b/src/client/models/agentRunRequest.ts
@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AgentRunRequest {
+  /** @nullable */
+  conversation_id?: string | null;
+  input: string;
+  /**
+     * @minimum 0
+     * @nullable
+     */
+  max_steps?: number | null;
+  session_id: string;
+  stream?: boolean;
+  /**
+     * @minimum 0
+     * @nullable
+     */
+  timeout_secs?: number | null;
+}
diff --git a/src/client/models/agentRunResponse.ts b/src/client/models/agentRunResponse.ts
new file mode 100644
index 0000000..c92f760
--- /dev/null
+++ b/src/client/models/agentRunResponse.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { AgentCostInfo } from './agentCostInfo';
+import type { AgentStepInfo } from './agentStepInfo';
+import type { AgentUsageInfo } from './agentUsageInfo';
+
+export interface AgentRunResponse {
+  conversation_id: string;
+  cost?: null | AgentCostInfo;
+  message_id: string;
+  output: string;
+  steps: AgentStepInfo[];
+  usage: AgentUsageInfo;
+}
diff --git a/src/client/models/agentSessionResponse.ts b/src/client/models/agentSessionResponse.ts
new file mode 100644
index 0000000..0de9d31
--- /dev/null
+++ b/src/client/models/agentSessionResponse.ts
@@ -0,0 +1,48 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AgentSessionResponse {
+  agent_kind: string;
+  created_at: string;
+  /** @nullable */
+  description?: string | null;
+  enabled: boolean;
+  id: string;
+  /** @nullable */
+  iteration_budget?: number | null;
+  /** @nullable */
+  max_output_tokens?: number | null;
+  /** @nullable */
+  memory_provider?: string | null;
+  /** @nullable */
+  model_version?: string | null;
+  name: string;
+  /** @nullable */
+  parent_session_id?: string | null;
+  /** @nullable */
+  published_at?: string | null;
+  /** @nullable */
+  source?: string | null;
+  /** @nullable */
+  system_prompt?: string | null;
+  /** @nullable */
+  temperature?: number | null;
+  /** @nullable */
+  tool_policy?: string | null;
+  /** @nullable */
+  toolset_json?: string | null;
+  updated_at: string;
+  /** @nullable */
+  user?: string | null;
+  /** @nullable */
+  variables?: string | null;
+  version: number;
+  visibility: string;
+  /** @nullable */
+  wk?: string | null;
+}
diff --git a/src/client/models/agentStepInfo.ts b/src/client/models/agentStepInfo.ts
new file mode 100644
index 0000000..67b5b08
--- /dev/null
+++ b/src/client/models/agentStepInfo.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { AgentToolCallInfo } from './agentToolCallInfo';
+
+export interface AgentStepInfo {
+  /** @nullable */
+  assistant?: string | null;
+  /** @minimum 0 */
+  index: number;
+  /** @nullable */
+  reflection?: string | null;
+  tool_calls: AgentToolCallInfo[];
+}
diff --git a/src/client/models/agentToolCallInfo.ts b/src/client/models/agentToolCallInfo.ts
new file mode 100644
index 0000000..bba15b1
--- /dev/null
+++ b/src/client/models/agentToolCallInfo.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AgentToolCallInfo {
+  arguments: unknown;
+  /** @nullable */
+  elapsed_ms?: number | null;
+  /** @nullable */
+  error?: string | null;
+  id: string;
+  name: string;
+  output?: unknown;
+}
diff --git a/src/client/models/agentUsageInfo.ts b/src/client/models/agentUsageInfo.ts
new file mode 100644
index 0000000..ba1e260
--- /dev/null
+++ b/src/client/models/agentUsageInfo.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AgentUsageInfo {
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+}
diff --git a/src/client/models/aiAddRequest.ts b/src/client/models/aiAddRequest.ts
new file mode 100644
index 0000000..6f5b9e7
--- /dev/null
+++ b/src/client/models/aiAddRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AiAddRequest {
+  agent_session: string;
+}
diff --git a/src/client/models/aiDiscussionResponse.ts b/src/client/models/aiDiscussionResponse.ts
new file mode 100644
index 0000000..24ab2ed
--- /dev/null
+++ b/src/client/models/aiDiscussionResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface AiDiscussionResponse {
+  author: IssueAuthor;
+  body: string;
+  created_at: string;
+  id: string;
+  /** @nullable */
+  parent?: string | null;
+  updated_at: string;
+}
diff --git a/src/client/models/aiLikeResponse.ts b/src/client/models/aiLikeResponse.ts
new file mode 100644
index 0000000..db18cbc
--- /dev/null
+++ b/src/client/models/aiLikeResponse.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface AiLikeResponse {
+  created_at: string;
+  user: IssueAuthor;
+}
diff --git a/src/client/models/aiListDiscussionsParams.ts b/src/client/models/aiListDiscussionsParams.ts
new file mode 100644
index 0000000..0a05196
--- /dev/null
+++ b/src/client/models/aiListDiscussionsParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type AiListDiscussionsParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/aiListModelsParams.ts b/src/client/models/aiListModelsParams.ts
new file mode 100644
index 0000000..1106af9
--- /dev/null
+++ b/src/client/models/aiListModelsParams.ts
@@ -0,0 +1,36 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type AiListModelsParams = {
+/**
+ * @nullable
+ */
+enabled?: boolean | null;
+/**
+ * @nullable
+ */
+provider?: string | null;
+/**
+ * @nullable
+ */
+modality?: string | null;
+/**
+ * @nullable
+ */
+name?: string | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/aiModelCardResponse.ts b/src/client/models/aiModelCardResponse.ts
new file mode 100644
index 0000000..9ed369e
--- /dev/null
+++ b/src/client/models/aiModelCardResponse.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AiModelCardResponse {
+  /** @nullable */
+  eval_summary?: string | null;
+  /** @nullable */
+  limitations?: string | null;
+  /** @nullable */
+  metadata?: string | null;
+  /** @nullable */
+  overview?: string | null;
+  /** @nullable */
+  safety_notes?: string | null;
+  /** @nullable */
+  strengths?: string | null;
+}
diff --git a/src/client/models/aiModelListItem.ts b/src/client/models/aiModelListItem.ts
new file mode 100644
index 0000000..3295f11
--- /dev/null
+++ b/src/client/models/aiModelListItem.ts
@@ -0,0 +1,28 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AiModelListItem {
+  /** @nullable */
+  context_window?: number | null;
+  created_at: string;
+  /** @nullable */
+  description?: string | null;
+  display_name: string;
+  enabled: boolean;
+  id: string;
+  /** @nullable */
+  input_token_limit?: number | null;
+  modality: string;
+  name: string;
+  /** @nullable */
+  output_token_limit?: number | null;
+  /** @nullable */
+  provider_logo_url?: string | null;
+  provider_name: string;
+  updated_at: string;
+}
diff --git a/src/client/models/aiModelResponse.ts b/src/client/models/aiModelResponse.ts
new file mode 100644
index 0000000..7ad4f46
--- /dev/null
+++ b/src/client/models/aiModelResponse.ts
@@ -0,0 +1,35 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { AiModelCardResponse } from './aiModelCardResponse';
+import type { AiModelVersionResponse } from './aiModelVersionResponse';
+
+export interface AiModelResponse {
+  card?: null | AiModelCardResponse;
+  /** @nullable */
+  context_window?: number | null;
+  created_at: string;
+  /** @nullable */
+  description?: string | null;
+  display_name: string;
+  enabled: boolean;
+  id: string;
+  /** @nullable */
+  input_token_limit?: number | null;
+  like_count: number;
+  modality: string;
+  name: string;
+  /** @nullable */
+  output_token_limit?: number | null;
+  /** @nullable */
+  provider_logo_url?: string | null;
+  provider_name: string;
+  public: boolean;
+  tags: string[];
+  updated_at: string;
+  versions: AiModelVersionResponse[];
+}
diff --git a/src/client/models/aiModelVersionResponse.ts b/src/client/models/aiModelVersionResponse.ts
new file mode 100644
index 0000000..c907f1d
--- /dev/null
+++ b/src/client/models/aiModelVersionResponse.ts
@@ -0,0 +1,26 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AiModelVersionResponse {
+  /** @nullable */
+  cached_input_price_per_million?: string | null;
+  /** @nullable */
+  deprecated_at?: string | null;
+  enabled: boolean;
+  id: string;
+  /** @nullable */
+  input_price_per_million?: string | null;
+  /** @nullable */
+  output_price_per_million?: string | null;
+  provider_model_name: string;
+  /** @nullable */
+  released_at?: string | null;
+  /** @nullable */
+  training_cutoff?: string | null;
+  version: string;
+}
diff --git a/src/client/models/aiProviderResponse.ts b/src/client/models/aiProviderResponse.ts
new file mode 100644
index 0000000..84b8df2
--- /dev/null
+++ b/src/client/models/aiProviderResponse.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AiProviderResponse {
+  /** @nullable */
+  base_url?: string | null;
+  created_at: string;
+  enabled: boolean;
+  id: string;
+  /** @nullable */
+  logo_url?: string | null;
+  name: string;
+  updated_at: string;
+  /** @nullable */
+  website_url?: string | null;
+}
diff --git a/src/client/models/appNotificationItem.ts b/src/client/models/appNotificationItem.ts
new file mode 100644
index 0000000..4624cad
--- /dev/null
+++ b/src/client/models/appNotificationItem.ts
@@ -0,0 +1,9 @@
+export interface AppNotificationItem {
+  body: string;
+  created_at: string;
+  id: string;
+  notify_type: string;
+  /** @nullable */
+  read_at?: string | null;
+  title: string;
+}
diff --git a/src/client/models/approveWorkspaceJoinApply.ts b/src/client/models/approveWorkspaceJoinApply.ts
new file mode 100644
index 0000000..f18dc04
--- /dev/null
+++ b/src/client/models/approveWorkspaceJoinApply.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ApproveWorkspaceJoinApply {
+  approved: boolean;
+  /** @nullable */
+  reason?: string | null;
+}
diff --git a/src/client/models/assignIssueUser.ts b/src/client/models/assignIssueUser.ts
new file mode 100644
index 0000000..b390e06
--- /dev/null
+++ b/src/client/models/assignIssueUser.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AssignIssueUser {
+  username: string;
+}
diff --git a/src/client/models/assignPrUser.ts b/src/client/models/assignPrUser.ts
new file mode 100644
index 0000000..790f867
--- /dev/null
+++ b/src/client/models/assignPrUser.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AssignPrUser {
+  username: string;
+}
diff --git a/src/client/models/authCaptchaParams.ts b/src/client/models/authCaptchaParams.ts
new file mode 100644
index 0000000..1cbe68c
--- /dev/null
+++ b/src/client/models/authCaptchaParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type AuthCaptchaParams = {
+/**
+ * @minimum 0
+ */
+w: number;
+/**
+ * @minimum 0
+ */
+h: number;
+dark: boolean;
+rsa: boolean;
+};
diff --git a/src/client/models/avatarUploadResponse.ts b/src/client/models/avatarUploadResponse.ts
new file mode 100644
index 0000000..ac764bf
--- /dev/null
+++ b/src/client/models/avatarUploadResponse.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface AvatarUploadResponse {
+  avatar_url: string;
+}
diff --git a/src/client/models/banCreateRequest.ts b/src/client/models/banCreateRequest.ts
new file mode 100644
index 0000000..93b8b02
--- /dev/null
+++ b/src/client/models/banCreateRequest.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BanCreateRequest {
+  /** @nullable */
+  expires_at?: string | null;
+  /** @nullable */
+  reason?: string | null;
+  user: string;
+}
diff --git a/src/client/models/bindIssuePullRequest.ts b/src/client/models/bindIssuePullRequest.ts
new file mode 100644
index 0000000..0d41482
--- /dev/null
+++ b/src/client/models/bindIssuePullRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BindIssuePullRequest {
+  pull_request_id: string;
+}
diff --git a/src/client/models/bindIssueRepo.ts b/src/client/models/bindIssueRepo.ts
new file mode 100644
index 0000000..bb83681
--- /dev/null
+++ b/src/client/models/bindIssueRepo.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BindIssueRepo {
+  repo_id: string;
+}
diff --git a/src/client/models/blameFileResponseDto.ts b/src/client/models/blameFileResponseDto.ts
new file mode 100644
index 0000000..cc5e348
--- /dev/null
+++ b/src/client/models/blameFileResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CommitBlameHunkDto } from './commitBlameHunkDto';
+
+export interface BlameFileResponseDto {
+  hunks: CommitBlameHunkDto[];
+}
diff --git a/src/client/models/blobInfoResponse.ts b/src/client/models/blobInfoResponse.ts
new file mode 100644
index 0000000..b646221
--- /dev/null
+++ b/src/client/models/blobInfoResponse.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { BlobLoadResponseDto } from './blobLoadResponseDto';
+
+export type BlobInfoResponse = BlobLoadResponseDto & {
+  is_binary: boolean;
+  /** @minimum 0 */
+  size: number;
+};
diff --git a/src/client/models/blobLoadResponseDto.ts b/src/client/models/blobLoadResponseDto.ts
new file mode 100644
index 0000000..3d8910a
--- /dev/null
+++ b/src/client/models/blobLoadResponseDto.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BlobLoadResponseDto {
+  blob: string;
+}
diff --git a/src/client/models/blobUploadBody.ts b/src/client/models/blobUploadBody.ts
new file mode 100644
index 0000000..08f07ac
--- /dev/null
+++ b/src/client/models/blobUploadBody.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BlobUploadBody {
+  /** @items.minimum 0 */
+  blob: number[];
+  path: string;
+}
diff --git a/src/client/models/blobUploadResponseDto.ts b/src/client/models/blobUploadResponseDto.ts
new file mode 100644
index 0000000..1385000
--- /dev/null
+++ b/src/client/models/blobUploadResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BlobUploadResponseDto {
+  /** @nullable */
+  id?: string | null;
+}
diff --git a/src/client/models/branchAheadBehindResponseDto.ts b/src/client/models/branchAheadBehindResponseDto.ts
new file mode 100644
index 0000000..eb0cedf
--- /dev/null
+++ b/src/client/models/branchAheadBehindResponseDto.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BranchAheadBehindResponseDto {
+  /** @minimum 0 */
+  ahead: number;
+  /** @minimum 0 */
+  behind: number;
+}
diff --git a/src/client/models/branchInfoResponseDto.ts b/src/client/models/branchInfoResponseDto.ts
new file mode 100644
index 0000000..9342c38
--- /dev/null
+++ b/src/client/models/branchInfoResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { BranchListItemDto } from './branchListItemDto';
+
+export interface BranchInfoResponseDto {
+  branch?: null | BranchListItemDto;
+}
diff --git a/src/client/models/branchListItemDto.ts b/src/client/models/branchListItemDto.ts
new file mode 100644
index 0000000..3d0baaf
--- /dev/null
+++ b/src/client/models/branchListItemDto.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BranchListItemDto {
+  is_current: boolean;
+  is_head: boolean;
+  is_remote: boolean;
+  name: string;
+  oid: string;
+  /** @nullable */
+  upstream?: string | null;
+}
diff --git a/src/client/models/branchListResponseDto.ts b/src/client/models/branchListResponseDto.ts
new file mode 100644
index 0000000..c913fdb
--- /dev/null
+++ b/src/client/models/branchListResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { BranchListItemDto } from './branchListItemDto';
+
+export interface BranchListResponseDto {
+  branches: BranchListItemDto[];
+}
diff --git a/src/client/models/branchUpstreamResponseDto.ts b/src/client/models/branchUpstreamResponseDto.ts
new file mode 100644
index 0000000..3f740ad
--- /dev/null
+++ b/src/client/models/branchUpstreamResponseDto.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface BranchUpstreamResponseDto {
+  upstream_name: string;
+}
diff --git a/src/client/models/captchaQuery.ts b/src/client/models/captchaQuery.ts
new file mode 100644
index 0000000..ad2795d
--- /dev/null
+++ b/src/client/models/captchaQuery.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CaptchaQuery {
+  dark: boolean;
+  /** @minimum 0 */
+  h: number;
+  rsa: boolean;
+  /** @minimum 0 */
+  w: number;
+}
diff --git a/src/client/models/captchaResponse.ts b/src/client/models/captchaResponse.ts
new file mode 100644
index 0000000..24fecb2
--- /dev/null
+++ b/src/client/models/captchaResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CaptchaQuery } from './captchaQuery';
+import type { RsaResponse } from './rsaResponse';
+
+export interface CaptchaResponse {
+  base64: string;
+  req: CaptchaQuery;
+  rsa?: null | RsaResponse;
+}
diff --git a/src/client/models/categoryCreateRequest.ts b/src/client/models/categoryCreateRequest.ts
new file mode 100644
index 0000000..2d28399
--- /dev/null
+++ b/src/client/models/categoryCreateRequest.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CategoryCreateRequest {
+  name: string;
+  /** @nullable */
+  position?: number | null;
+}
diff --git a/src/client/models/categoryUpdateRequest.ts b/src/client/models/categoryUpdateRequest.ts
new file mode 100644
index 0000000..7d10f04
--- /dev/null
+++ b/src/client/models/categoryUpdateRequest.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CategoryUpdateRequest {
+  /** @nullable */
+  name?: string | null;
+  /** @nullable */
+  position?: number | null;
+}
diff --git a/src/client/models/channelListMessagesParams.ts b/src/client/models/channelListMessagesParams.ts
new file mode 100644
index 0000000..36a4008
--- /dev/null
+++ b/src/client/models/channelListMessagesParams.ts
@@ -0,0 +1,23 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type ChannelListMessagesParams = {
+/**
+ * @nullable
+ */
+before_seq?: number | null;
+/**
+ * @nullable
+ */
+after_seq?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/channelMessagesAroundParams.ts b/src/client/models/channelMessagesAroundParams.ts
new file mode 100644
index 0000000..819cf3d
--- /dev/null
+++ b/src/client/models/channelMessagesAroundParams.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type ChannelMessagesAroundParams = {
+seq: number;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/channelMissedMessagesParams.ts b/src/client/models/channelMissedMessagesParams.ts
new file mode 100644
index 0000000..0e4719d
--- /dev/null
+++ b/src/client/models/channelMissedMessagesParams.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type ChannelMissedMessagesParams = {
+after_seq: number;
+/**
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/channelSearchParams.ts b/src/client/models/channelSearchParams.ts
new file mode 100644
index 0000000..4184a66
--- /dev/null
+++ b/src/client/models/channelSearchParams.ts
@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type ChannelSearchParams = {
+q: string;
+/**
+ * @nullable
+ */
+room?: string | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+};
diff --git a/src/client/models/cherryPickResponseDto.ts b/src/client/models/cherryPickResponseDto.ts
new file mode 100644
index 0000000..f39b753
--- /dev/null
+++ b/src/client/models/cherryPickResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CherryPickResponseDto {
+  /** @nullable */
+  oid?: string | null;
+}
diff --git a/src/client/models/cloneRepo.ts b/src/client/models/cloneRepo.ts
new file mode 100644
index 0000000..31b55ea
--- /dev/null
+++ b/src/client/models/cloneRepo.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CloneRepo {
+  /** @nullable */
+  description?: string | null;
+  name: string;
+  source_url: string;
+  /** @nullable */
+  visibility?: string | null;
+}
diff --git a/src/client/models/combinedCommitStatus.ts b/src/client/models/combinedCommitStatus.ts
new file mode 100644
index 0000000..5537388
--- /dev/null
+++ b/src/client/models/combinedCommitStatus.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CommitStatusResponse } from './commitStatusResponse';
+
+export interface CombinedCommitStatus {
+  sha: string;
+  state: string;
+  statuses: CommitStatusResponse[];
+  total_count: number;
+}
diff --git a/src/client/models/commitBlameHunkDto.ts b/src/client/models/commitBlameHunkDto.ts
new file mode 100644
index 0000000..75ba84a
--- /dev/null
+++ b/src/client/models/commitBlameHunkDto.ts
@@ -0,0 +1,23 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CommitBlameHunkDto {
+  boundary: boolean;
+  /** @nullable */
+  commit_oid?: string | null;
+  /** @minimum 0 */
+  final_lines: number;
+  /** @minimum 0 */
+  final_start_line: number;
+  /** @minimum 0 */
+  orig_lines: number;
+  /** @nullable */
+  orig_path?: string | null;
+  /** @minimum 0 */
+  orig_start_line: number;
+}
diff --git a/src/client/models/commitHistoryResponseDto.ts b/src/client/models/commitHistoryResponseDto.ts
new file mode 100644
index 0000000..0e4bbaf
--- /dev/null
+++ b/src/client/models/commitHistoryResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CommitMetaDto } from './commitMetaDto';
+
+export interface CommitHistoryResponseDto {
+  commits: CommitMetaDto[];
+}
diff --git a/src/client/models/commitInfoResponseDto.ts b/src/client/models/commitInfoResponseDto.ts
new file mode 100644
index 0000000..9ddf042
--- /dev/null
+++ b/src/client/models/commitInfoResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CommitMetaDto } from './commitMetaDto';
+
+export interface CommitInfoResponseDto {
+  commit?: null | CommitMetaDto;
+}
diff --git a/src/client/models/commitMetaDto.ts b/src/client/models/commitMetaDto.ts
new file mode 100644
index 0000000..989e320
--- /dev/null
+++ b/src/client/models/commitMetaDto.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CommitSignatureDto } from './commitSignatureDto';
+
+export interface CommitMetaDto {
+  author?: null | CommitSignatureDto;
+  committer?: null | CommitSignatureDto;
+  /** @nullable */
+  encoding?: string | null;
+  message: string;
+  oid: string;
+  parent_ids: string[];
+  summary: string;
+  /** @nullable */
+  tree_id?: string | null;
+}
diff --git a/src/client/models/commitSignatureDto.ts b/src/client/models/commitSignatureDto.ts
new file mode 100644
index 0000000..2019af5
--- /dev/null
+++ b/src/client/models/commitSignatureDto.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CommitSignatureDto {
+  email: string;
+  name: string;
+  offset_minutes: number;
+  time_secs: number;
+}
diff --git a/src/client/models/commitStatusResponse.ts b/src/client/models/commitStatusResponse.ts
new file mode 100644
index 0000000..55eb00d
--- /dev/null
+++ b/src/client/models/commitStatusResponse.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CommitStatusResponse {
+  commit_sha: string;
+  context: string;
+  created_at: string;
+  creator: string;
+  /** @nullable */
+  description?: string | null;
+  id: string;
+  state: string;
+  /** @nullable */
+  target_url?: string | null;
+}
diff --git a/src/client/models/compareCommit.ts b/src/client/models/compareCommit.ts
new file mode 100644
index 0000000..5627f35
--- /dev/null
+++ b/src/client/models/compareCommit.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CompareCommit {
+  /** @nullable */
+  author_email?: string | null;
+  /** @nullable */
+  author_name?: string | null;
+  message: string;
+  sha: string;
+}
diff --git a/src/client/models/compareResponse.ts b/src/client/models/compareResponse.ts
new file mode 100644
index 0000000..3065d4e
--- /dev/null
+++ b/src/client/models/compareResponse.ts
@@ -0,0 +1,23 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { CompareCommit } from './compareCommit';
+
+export interface CompareResponse {
+  ahead_by: number;
+  base_commit: CompareCommit;
+  behind_by: number;
+  commits: CompareCommit[];
+  /** @minimum 0 */
+  deletions: number;
+  /** @minimum 0 */
+  files_changed: number;
+  head_commit: CompareCommit;
+  /** @minimum 0 */
+  insertions: number;
+  total_commits: number;
+}
diff --git a/src/client/models/contentResponse.ts b/src/client/models/contentResponse.ts
new file mode 100644
index 0000000..a6f3f61
--- /dev/null
+++ b/src/client/models/contentResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ContentResponse {
+  /** @nullable */
+  content?: string | null;
+  /** @nullable */
+  encoding?: string | null;
+  name: string;
+  path: string;
+  size: number;
+  type: string;
+}
diff --git a/src/client/models/contextMe.ts b/src/client/models/contextMe.ts
new file mode 100644
index 0000000..82abae7
--- /dev/null
+++ b/src/client/models/contextMe.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ContextMe {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  display_name?: string | null;
+  /** @minimum 0 */
+  has_unread_notifications: number;
+  id: string;
+  language: string;
+  timezone: string;
+  username: string;
+}
diff --git a/src/client/models/contributionHeatmapItem.ts b/src/client/models/contributionHeatmapItem.ts
new file mode 100644
index 0000000..ea463eb
--- /dev/null
+++ b/src/client/models/contributionHeatmapItem.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ContributionHeatmapItem {
+  count: number;
+  date: string;
+}
diff --git a/src/client/models/contributionHeatmapResponse.ts b/src/client/models/contributionHeatmapResponse.ts
new file mode 100644
index 0000000..2542136
--- /dev/null
+++ b/src/client/models/contributionHeatmapResponse.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { ContributionHeatmapItem } from './contributionHeatmapItem';
+
+export interface ContributionHeatmapResponse {
+  end_date: string;
+  heatmap: ContributionHeatmapItem[];
+  start_date: string;
+  total_contributions: number;
+  username: string;
+}
diff --git a/src/client/models/contributorDto.ts b/src/client/models/contributorDto.ts
new file mode 100644
index 0000000..d031848
--- /dev/null
+++ b/src/client/models/contributorDto.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ContributorDto {
+  commit_count: number;
+  email: string;
+  name: string;
+  /** @nullable */
+  user_id?: string | null;
+}
diff --git a/src/client/models/conversationResponse.ts b/src/client/models/conversationResponse.ts
new file mode 100644
index 0000000..1fe7098
--- /dev/null
+++ b/src/client/models/conversationResponse.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ConversationResponse {
+  /** @nullable */
+  archived_at?: string | null;
+  created_at: string;
+  created_by: string;
+  id: string;
+  /** @nullable */
+  last_message_at?: string | null;
+  session_id: string;
+  title: string;
+  updated_at: string;
+}
diff --git a/src/client/models/conversationWithSessionResponse.ts b/src/client/models/conversationWithSessionResponse.ts
new file mode 100644
index 0000000..0b1a35a
--- /dev/null
+++ b/src/client/models/conversationWithSessionResponse.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ConversationWithSessionResponse {
+  /** @nullable */
+  archived_at?: string | null;
+  created_at: string;
+  created_by: string;
+  id: string;
+  /** @nullable */
+  last_message_at?: string | null;
+  session_id: string;
+  /** @nullable */
+  session_name?: string | null;
+  title: string;
+  updated_at: string;
+}
diff --git a/src/client/models/createAgentSession.ts b/src/client/models/createAgentSession.ts
new file mode 100644
index 0000000..cc61d27
--- /dev/null
+++ b/src/client/models/createAgentSession.ts
@@ -0,0 +1,41 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateAgentSession {
+  agent_kind: string;
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  iteration_budget?: number | null;
+  /** @nullable */
+  knowledge_base_ids?: string[] | null;
+  /** @nullable */
+  max_output_tokens?: number | null;
+  /** @nullable */
+  memory_provider?: string | null;
+  /** @nullable */
+  memory_provider_config?: string | null;
+  model_version: string;
+  name: string;
+  /** @nullable */
+  source?: string | null;
+  /** @nullable */
+  system_prompt?: string | null;
+  /** @nullable */
+  temperature?: number | null;
+  /** @nullable */
+  tool_policy?: string | null;
+  /** @nullable */
+  toolset_json?: string | null;
+  /** @nullable */
+  variables?: string | null;
+  /** @nullable */
+  visibility?: string | null;
+  /** @nullable */
+  wk?: string | null;
+}
diff --git a/src/client/models/createComment.ts b/src/client/models/createComment.ts
new file mode 100644
index 0000000..b820f10
--- /dev/null
+++ b/src/client/models/createComment.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateComment {
+  body: string;
+}
diff --git a/src/client/models/createCommitStatus.ts b/src/client/models/createCommitStatus.ts
new file mode 100644
index 0000000..d014060
--- /dev/null
+++ b/src/client/models/createCommitStatus.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateCommitStatus {
+  /** @nullable */
+  context?: string | null;
+  /** @nullable */
+  description?: string | null;
+  state: string;
+  /** @nullable */
+  target_url?: string | null;
+}
diff --git a/src/client/models/createContent.ts b/src/client/models/createContent.ts
new file mode 100644
index 0000000..3371c0d
--- /dev/null
+++ b/src/client/models/createContent.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateContent {
+  /** @nullable */
+  branch?: string | null;
+  content: string;
+  message: string;
+}
diff --git a/src/client/models/createConversation.ts b/src/client/models/createConversation.ts
new file mode 100644
index 0000000..07950a4
--- /dev/null
+++ b/src/client/models/createConversation.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateConversation {
+  title: string;
+}
diff --git a/src/client/models/createFork.ts b/src/client/models/createFork.ts
new file mode 100644
index 0000000..90755b0
--- /dev/null
+++ b/src/client/models/createFork.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateFork {
+  /** @nullable */
+  name?: string | null;
+  /** @nullable */
+  visibility?: string | null;
+}
diff --git a/src/client/models/createIssue.ts b/src/client/models/createIssue.ts
new file mode 100644
index 0000000..28668f1
--- /dev/null
+++ b/src/client/models/createIssue.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateIssue {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  due_at?: string | null;
+  /** @nullable */
+  priority?: string | null;
+  title: string;
+}
diff --git a/src/client/models/createLabel.ts b/src/client/models/createLabel.ts
new file mode 100644
index 0000000..c579f1d
--- /dev/null
+++ b/src/client/models/createLabel.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateLabel {
+  color: string;
+  /** @nullable */
+  description?: string | null;
+  name: string;
+}
diff --git a/src/client/models/createMessageRequest.ts b/src/client/models/createMessageRequest.ts
new file mode 100644
index 0000000..df3faa9
--- /dev/null
+++ b/src/client/models/createMessageRequest.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateMessageRequest {
+  content: string;
+  /** @nullable */
+  content_type?: string | null;
+  /** @nullable */
+  in_reply_to?: string | null;
+  /** @nullable */
+  thread?: string | null;
+}
diff --git a/src/client/models/createMilestone.ts b/src/client/models/createMilestone.ts
new file mode 100644
index 0000000..3e74319
--- /dev/null
+++ b/src/client/models/createMilestone.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateMilestone {
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  due_at?: string | null;
+  title: string;
+}
diff --git a/src/client/models/createPrComment.ts b/src/client/models/createPrComment.ts
new file mode 100644
index 0000000..cf0c162
--- /dev/null
+++ b/src/client/models/createPrComment.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreatePrComment {
+  body: string;
+}
diff --git a/src/client/models/createPrReview.ts b/src/client/models/createPrReview.ts
new file mode 100644
index 0000000..52fc5a5
--- /dev/null
+++ b/src/client/models/createPrReview.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreatePrReview {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  commit_sha?: string | null;
+  state: string;
+}
diff --git a/src/client/models/createPrReviewComment.ts b/src/client/models/createPrReviewComment.ts
new file mode 100644
index 0000000..9791f92
--- /dev/null
+++ b/src/client/models/createPrReviewComment.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreatePrReviewComment {
+  body: string;
+  /** @nullable */
+  commit_sha?: string | null;
+  /** @nullable */
+  line?: number | null;
+  path: string;
+  /** @nullable */
+  side?: string | null;
+}
diff --git a/src/client/models/createProtect.ts b/src/client/models/createProtect.ts
new file mode 100644
index 0000000..18bdaba
--- /dev/null
+++ b/src/client/models/createProtect.ts
@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateProtect {
+  /** @nullable */
+  allow_deletions?: boolean | null;
+  /** @nullable */
+  allow_force_pushes?: boolean | null;
+  /** @nullable */
+  enforce_admins?: boolean | null;
+  pattern: string;
+  /** @nullable */
+  require_pull_request?: boolean | null;
+  /** @nullable */
+  require_status_checks?: boolean | null;
+  /** @nullable */
+  required_approvals?: number | null;
+  /** @nullable */
+  required_status_contexts?: string[] | null;
+}
diff --git a/src/client/models/createPullRequest.ts b/src/client/models/createPullRequest.ts
new file mode 100644
index 0000000..a5b15dc
--- /dev/null
+++ b/src/client/models/createPullRequest.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreatePullRequest {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  draft?: boolean | null;
+  source_branch: string;
+  /** @nullable */
+  source_repo?: string | null;
+  /** @nullable */
+  target_branch?: string | null;
+  title: string;
+}
diff --git a/src/client/models/createRelease.ts b/src/client/models/createRelease.ts
new file mode 100644
index 0000000..e6babd1
--- /dev/null
+++ b/src/client/models/createRelease.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateRelease {
+  /** @nullable */
+  body?: string | null;
+  draft?: boolean;
+  name: string;
+  prerelease?: boolean;
+  tag_name: string;
+  /** @nullable */
+  target_commit_sha?: string | null;
+}
diff --git a/src/client/models/createRepo.ts b/src/client/models/createRepo.ts
new file mode 100644
index 0000000..08e3098
--- /dev/null
+++ b/src/client/models/createRepo.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateRepo {
+  /** @nullable */
+  default_branch?: string | null;
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  enable_lfs?: boolean | null;
+  /** @nullable */
+  initialize_with_readme?: boolean | null;
+  name: string;
+  /** @nullable */
+  visibility?: string | null;
+}
diff --git a/src/client/models/createUserAccessToken.ts b/src/client/models/createUserAccessToken.ts
new file mode 100644
index 0000000..c734168
--- /dev/null
+++ b/src/client/models/createUserAccessToken.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateUserAccessToken {
+  /** @nullable */
+  expires_at?: string | null;
+  name: string;
+  scopes: string[];
+}
diff --git a/src/client/models/createUserSshKey.ts b/src/client/models/createUserSshKey.ts
new file mode 100644
index 0000000..ce497e1
--- /dev/null
+++ b/src/client/models/createUserSshKey.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateUserSshKey {
+  /** @nullable */
+  expires_at?: string | null;
+  public_key: string;
+  title: string;
+}
diff --git a/src/client/models/createWebhook.ts b/src/client/models/createWebhook.ts
new file mode 100644
index 0000000..6025fda
--- /dev/null
+++ b/src/client/models/createWebhook.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateWebhook {
+  /** @nullable */
+  active?: boolean | null;
+  events: string[];
+  /** @nullable */
+  secret?: string | null;
+  url: string;
+}
diff --git a/src/client/models/createWorkspace.ts b/src/client/models/createWorkspace.ts
new file mode 100644
index 0000000..b9cc904
--- /dev/null
+++ b/src/client/models/createWorkspace.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateWorkspace {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  description?: string | null;
+  name: string;
+}
diff --git a/src/client/models/createWorkspaceGroup.ts b/src/client/models/createWorkspaceGroup.ts
new file mode 100644
index 0000000..642cd8b
--- /dev/null
+++ b/src/client/models/createWorkspaceGroup.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateWorkspaceGroup {
+  /** @nullable */
+  avatar_url?: string | null;
+  name: string;
+}
diff --git a/src/client/models/createWorkspaceJoinApply.ts b/src/client/models/createWorkspaceJoinApply.ts
new file mode 100644
index 0000000..0be4aa0
--- /dev/null
+++ b/src/client/models/createWorkspaceJoinApply.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CreateWorkspaceJoinApply {
+  /** @nullable */
+  answer?: string | null;
+  /** @nullable */
+  message?: string | null;
+}
diff --git a/src/client/models/createdUserAccessToken.ts b/src/client/models/createdUserAccessToken.ts
new file mode 100644
index 0000000..cf9c389
--- /dev/null
+++ b/src/client/models/createdUserAccessToken.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { UserAccessToken } from './userAccessToken';
+
+export interface CreatedUserAccessToken {
+  access_token: UserAccessToken;
+  token: string;
+}
diff --git a/src/client/models/customStatusRequest.ts b/src/client/models/customStatusRequest.ts
new file mode 100644
index 0000000..6e76aed
--- /dev/null
+++ b/src/client/models/customStatusRequest.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface CustomStatusRequest {
+  /** @nullable */
+  emoji?: string | null;
+  /** @nullable */
+  expires_at?: string | null;
+  /** @nullable */
+  text?: string | null;
+}
diff --git a/src/client/models/diffDeltaDto.ts b/src/client/models/diffDeltaDto.ts
new file mode 100644
index 0000000..484c73a
--- /dev/null
+++ b/src/client/models/diffDeltaDto.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { DiffFileDto } from './diffFileDto';
+import type { DiffHunkDto } from './diffHunkDto';
+import type { DiffLineDto } from './diffLineDto';
+
+export interface DiffDeltaDto {
+  hunks: DiffHunkDto[];
+  lines: DiffLineDto[];
+  new_file?: null | DiffFileDto;
+  /** @minimum 0 */
+  nfiles: number;
+  old_file?: null | DiffFileDto;
+  status: number;
+}
diff --git a/src/client/models/diffFileDto.ts b/src/client/models/diffFileDto.ts
new file mode 100644
index 0000000..4201bff
--- /dev/null
+++ b/src/client/models/diffFileDto.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DiffFileDto {
+  is_binary: boolean;
+  /** @nullable */
+  oid?: string | null;
+  /** @nullable */
+  path?: string | null;
+  /** @minimum 0 */
+  size: number;
+}
diff --git a/src/client/models/diffHunkDto.ts b/src/client/models/diffHunkDto.ts
new file mode 100644
index 0000000..32624f7
--- /dev/null
+++ b/src/client/models/diffHunkDto.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DiffHunkDto {
+  header: string;
+  /** @minimum 0 */
+  new_lines: number;
+  /** @minimum 0 */
+  new_start: number;
+  /** @minimum 0 */
+  old_lines: number;
+  /** @minimum 0 */
+  old_start: number;
+}
diff --git a/src/client/models/diffLineDto.ts b/src/client/models/diffLineDto.ts
new file mode 100644
index 0000000..f0b4753
--- /dev/null
+++ b/src/client/models/diffLineDto.ts
@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DiffLineDto {
+  content: string;
+  content_offset: number;
+  /**
+     * @minimum 0
+     * @nullable
+     */
+  new_lineno?: number | null;
+  /** @minimum 0 */
+  num_lines: number;
+  /**
+     * @minimum 0
+     * @nullable
+     */
+  old_lineno?: number | null;
+  origin: string;
+}
diff --git a/src/client/models/diffResultDto.ts b/src/client/models/diffResultDto.ts
new file mode 100644
index 0000000..2680e58
--- /dev/null
+++ b/src/client/models/diffResultDto.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { DiffDeltaDto } from './diffDeltaDto';
+import type { DiffStatsDto } from './diffStatsDto';
+
+export interface DiffResultDto {
+  deltas: DiffDeltaDto[];
+  stats?: null | DiffStatsDto;
+}
diff --git a/src/client/models/diffStatsDto.ts b/src/client/models/diffStatsDto.ts
new file mode 100644
index 0000000..1d72299
--- /dev/null
+++ b/src/client/models/diffStatsDto.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DiffStatsDto {
+  /** @minimum 0 */
+  deletions: number;
+  /** @minimum 0 */
+  files_changed: number;
+  /** @minimum 0 */
+  insertions: number;
+}
diff --git a/src/client/models/disable2FAParams.ts b/src/client/models/disable2FAParams.ts
new file mode 100644
index 0000000..8a12072
--- /dev/null
+++ b/src/client/models/disable2FAParams.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface Disable2FAParams {
+  code: string;
+  password: string;
+}
diff --git a/src/client/models/dismissPrReview.ts b/src/client/models/dismissPrReview.ts
new file mode 100644
index 0000000..4ffd7eb
--- /dev/null
+++ b/src/client/models/dismissPrReview.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DismissPrReview {
+  /** @nullable */
+  dismiss_reason?: string | null;
+}
diff --git a/src/client/models/dndRequest.ts b/src/client/models/dndRequest.ts
new file mode 100644
index 0000000..ee6c5ea
--- /dev/null
+++ b/src/client/models/dndRequest.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DndRequest {
+  /** @nullable */
+  dnd_end_hour?: number | null;
+  /** @nullable */
+  dnd_start_hour?: number | null;
+  /** @nullable */
+  do_not_disturb?: boolean | null;
+}
diff --git a/src/client/models/draftSaveRequest.ts b/src/client/models/draftSaveRequest.ts
new file mode 100644
index 0000000..f840a53
--- /dev/null
+++ b/src/client/models/draftSaveRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface DraftSaveRequest {
+  content: string;
+}
diff --git a/src/client/models/emailChangeRequest.ts b/src/client/models/emailChangeRequest.ts
new file mode 100644
index 0000000..1894451
--- /dev/null
+++ b/src/client/models/emailChangeRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface EmailChangeRequest {
+  new_email: string;
+  password: string;
+}
diff --git a/src/client/models/emailResponse.ts b/src/client/models/emailResponse.ts
new file mode 100644
index 0000000..f609e0f
--- /dev/null
+++ b/src/client/models/emailResponse.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface EmailResponse {
+  /** @nullable */
+  email?: string | null;
+}
diff --git a/src/client/models/emailVerifyRequest.ts b/src/client/models/emailVerifyRequest.ts
new file mode 100644
index 0000000..5bbc16a
--- /dev/null
+++ b/src/client/models/emailVerifyRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface EmailVerifyRequest {
+  token: string;
+}
diff --git a/src/client/models/enable2FAResponse.ts b/src/client/models/enable2FAResponse.ts
new file mode 100644
index 0000000..b07396c
--- /dev/null
+++ b/src/client/models/enable2FAResponse.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface Enable2FAResponse {
+  backup_codes: string[];
+  qr_code: string;
+  secret: string;
+}
diff --git a/src/client/models/forkResponse.ts b/src/client/models/forkResponse.ts
new file mode 100644
index 0000000..f3a0e9e
--- /dev/null
+++ b/src/client/models/forkResponse.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ForkResponse {
+  created_at: string;
+  default_branch: string;
+  /** @nullable */
+  description?: string | null;
+  forked_by: string;
+  id: string;
+  name: string;
+  source_repo: string;
+  visibility: string;
+}
diff --git a/src/client/models/get2FAStatusResponse.ts b/src/client/models/get2FAStatusResponse.ts
new file mode 100644
index 0000000..6790d2b
--- /dev/null
+++ b/src/client/models/get2FAStatusResponse.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface Get2FAStatusResponse {
+  has_backup_codes: boolean;
+  is_enabled: boolean;
+  /** @nullable */
+  method?: string | null;
+}
diff --git a/src/client/models/gitAheadBehindParams.ts b/src/client/models/gitAheadBehindParams.ts
new file mode 100644
index 0000000..cb3b21d
--- /dev/null
+++ b/src/client/models/gitAheadBehindParams.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitAheadBehindParams = {
+remote_branch: string;
+};
diff --git a/src/client/models/gitArchiveParams.ts b/src/client/models/gitArchiveParams.ts
new file mode 100644
index 0000000..14d9443
--- /dev/null
+++ b/src/client/models/gitArchiveParams.ts
@@ -0,0 +1,23 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitArchiveParams = {
+format?: string;
+/**
+ * @nullable
+ */
+tree?: string | null;
+/**
+ * @nullable
+ */
+prefix?: string | null;
+/**
+ * @nullable
+ */
+pathspec?: string[] | null;
+};
diff --git a/src/client/models/gitBlameFileParams.ts b/src/client/models/gitBlameFileParams.ts
new file mode 100644
index 0000000..aa822f9
--- /dev/null
+++ b/src/client/models/gitBlameFileParams.ts
@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitBlameFileParams = {
+path: string;
+/**
+ * @nullable
+ */
+rev?: string | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+start_line?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+end_line?: number | null;
+};
diff --git a/src/client/models/gitBlobInfoParams.ts b/src/client/models/gitBlobInfoParams.ts
new file mode 100644
index 0000000..8a50628
--- /dev/null
+++ b/src/client/models/gitBlobInfoParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitBlobInfoParams = {
+/**
+ * @nullable
+ */
+path?: string | null;
+};
diff --git a/src/client/models/gitCherryPickBody.ts b/src/client/models/gitCherryPickBody.ts
new file mode 100644
index 0000000..fc8de9c
--- /dev/null
+++ b/src/client/models/gitCherryPickBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitCherryPickBody = { [key: string]: unknown };
diff --git a/src/client/models/gitCommitHistoryParams.ts b/src/client/models/gitCommitHistoryParams.ts
new file mode 100644
index 0000000..1074fca
--- /dev/null
+++ b/src/client/models/gitCommitHistoryParams.ts
@@ -0,0 +1,28 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitCommitHistoryParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+skip?: number | null;
+/**
+ * @nullable
+ */
+sort?: number | null;
+/**
+ * @nullable
+ */
+branch?: string | null;
+};
diff --git a/src/client/models/gitCommitWalkBody.ts b/src/client/models/gitCommitWalkBody.ts
new file mode 100644
index 0000000..66226bf
--- /dev/null
+++ b/src/client/models/gitCommitWalkBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitCommitWalkBody = { [key: string]: unknown };
diff --git a/src/client/models/gitDeleteBranchParams.ts b/src/client/models/gitDeleteBranchParams.ts
new file mode 100644
index 0000000..a96374a
--- /dev/null
+++ b/src/client/models/gitDeleteBranchParams.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitDeleteBranchParams = {
+force?: boolean;
+};
diff --git a/src/client/models/gitDeleteContentsParams.ts b/src/client/models/gitDeleteContentsParams.ts
new file mode 100644
index 0000000..1346e07
--- /dev/null
+++ b/src/client/models/gitDeleteContentsParams.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitDeleteContentsParams = {
+message: string;
+sha: string;
+/**
+ * @nullable
+ */
+branch?: string | null;
+};
diff --git a/src/client/models/gitDiffBranchesParams.ts b/src/client/models/gitDiffBranchesParams.ts
new file mode 100644
index 0000000..67cb5d5
--- /dev/null
+++ b/src/client/models/gitDiffBranchesParams.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitDiffBranchesParams = {
+old_branch: string;
+new_branch: string;
+};
diff --git a/src/client/models/gitDiffParams.ts b/src/client/models/gitDiffParams.ts
new file mode 100644
index 0000000..5b81c04
--- /dev/null
+++ b/src/client/models/gitDiffParams.ts
@@ -0,0 +1,35 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitDiffParams = {
+/**
+ * @nullable
+ */
+old_oid?: string | null;
+/**
+ * @nullable
+ */
+new_oid?: string | null;
+/**
+ * @nullable
+ */
+old_tree?: string | null;
+/**
+ * @nullable
+ */
+new_tree?: string | null;
+/**
+ * @nullable
+ */
+tree_oid?: string | null;
+mode?: string;
+/**
+ * @nullable
+ */
+path?: string | null;
+};
diff --git a/src/client/models/gitForkBranchBody.ts b/src/client/models/gitForkBranchBody.ts
new file mode 100644
index 0000000..a75e444
--- /dev/null
+++ b/src/client/models/gitForkBranchBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitForkBranchBody = { [key: string]: unknown };
diff --git a/src/client/models/gitGetContentsParams.ts b/src/client/models/gitGetContentsParams.ts
new file mode 100644
index 0000000..db4e67e
--- /dev/null
+++ b/src/client/models/gitGetContentsParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitGetContentsParams = {
+/**
+ * @nullable
+ */
+ref?: string | null;
+};
diff --git a/src/client/models/gitInitTagBody.ts b/src/client/models/gitInitTagBody.ts
new file mode 100644
index 0000000..9d68e5a
--- /dev/null
+++ b/src/client/models/gitInitTagBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitInitTagBody = { [key: string]: unknown };
diff --git a/src/client/models/gitListBranchesParams.ts b/src/client/models/gitListBranchesParams.ts
new file mode 100644
index 0000000..c394d03
--- /dev/null
+++ b/src/client/models/gitListBranchesParams.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListBranchesParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+summary?: boolean;
+default_only?: boolean;
+};
diff --git a/src/client/models/gitListCommitsParams.ts b/src/client/models/gitListCommitsParams.ts
new file mode 100644
index 0000000..045eb9c
--- /dev/null
+++ b/src/client/models/gitListCommitsParams.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListCommitsParams = {
+summary?: boolean;
+refs?: boolean;
+/**
+ * @nullable
+ */
+prefix?: string | null;
+};
diff --git a/src/client/models/gitListContributorsParams.ts b/src/client/models/gitListContributorsParams.ts
new file mode 100644
index 0000000..fc88f91
--- /dev/null
+++ b/src/client/models/gitListContributorsParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListContributorsParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/gitListDeliveriesParams.ts b/src/client/models/gitListDeliveriesParams.ts
new file mode 100644
index 0000000..17e6e9e
--- /dev/null
+++ b/src/client/models/gitListDeliveriesParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListDeliveriesParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/gitListForksParams.ts b/src/client/models/gitListForksParams.ts
new file mode 100644
index 0000000..21ddb1f
--- /dev/null
+++ b/src/client/models/gitListForksParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListForksParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/gitListProtectsParams.ts b/src/client/models/gitListProtectsParams.ts
new file mode 100644
index 0000000..c509de5
--- /dev/null
+++ b/src/client/models/gitListProtectsParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListProtectsParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/gitListRefsParams.ts b/src/client/models/gitListRefsParams.ts
new file mode 100644
index 0000000..872770a
--- /dev/null
+++ b/src/client/models/gitListRefsParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListRefsParams = {
+/**
+ * @nullable
+ */
+ref?: string | null;
+};
diff --git a/src/client/models/gitListReposParams.ts b/src/client/models/gitListReposParams.ts
new file mode 100644
index 0000000..568ff3e
--- /dev/null
+++ b/src/client/models/gitListReposParams.ts
@@ -0,0 +1,32 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListReposParams = {
+/**
+ * @nullable
+ */
+visibility?: string | null;
+/**
+ * @nullable
+ */
+is_archived?: boolean | null;
+/**
+ * @nullable
+ */
+search?: string | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/gitListTagsParams.ts b/src/client/models/gitListTagsParams.ts
new file mode 100644
index 0000000..56017b0
--- /dev/null
+++ b/src/client/models/gitListTagsParams.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListTagsParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+summary?: boolean;
+};
diff --git a/src/client/models/gitListWebhooksParams.ts b/src/client/models/gitListWebhooksParams.ts
new file mode 100644
index 0000000..240a8f1
--- /dev/null
+++ b/src/client/models/gitListWebhooksParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitListWebhooksParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/gitRefResponse.ts b/src/client/models/gitRefResponse.ts
new file mode 100644
index 0000000..1b634f7
--- /dev/null
+++ b/src/client/models/gitRefResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface GitRefResponse {
+  is_default: boolean;
+  is_protected: boolean;
+  kind: string;
+  name: string;
+  target_sha: string;
+}
diff --git a/src/client/models/gitTreeEntriesParams.ts b/src/client/models/gitTreeEntriesParams.ts
new file mode 100644
index 0000000..8ee4f69
--- /dev/null
+++ b/src/client/models/gitTreeEntriesParams.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitTreeEntriesParams = {
+/**
+ * @nullable
+ */
+path?: string | null;
+last?: boolean;
+resolve?: boolean;
+};
diff --git a/src/client/models/gitTreeEntryByPathFromCommitParams.ts b/src/client/models/gitTreeEntryByPathFromCommitParams.ts
new file mode 100644
index 0000000..c636f2a
--- /dev/null
+++ b/src/client/models/gitTreeEntryByPathFromCommitParams.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitTreeEntryByPathFromCommitParams = {
+path: string;
+};
diff --git a/src/client/models/gitTreeEntryByPathParams.ts b/src/client/models/gitTreeEntryByPathParams.ts
new file mode 100644
index 0000000..e27e8f5
--- /dev/null
+++ b/src/client/models/gitTreeEntryByPathParams.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitTreeEntryByPathParams = {
+path: string;
+};
diff --git a/src/client/models/gitUpdateTagBody.ts b/src/client/models/gitUpdateTagBody.ts
new file mode 100644
index 0000000..714ba28
--- /dev/null
+++ b/src/client/models/gitUpdateTagBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitUpdateTagBody = { [key: string]: unknown };
diff --git a/src/client/models/gitWatchRepoBody.ts b/src/client/models/gitWatchRepoBody.ts
new file mode 100644
index 0000000..eaad848
--- /dev/null
+++ b/src/client/models/gitWatchRepoBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type GitWatchRepoBody = { [key: string]: unknown };
diff --git a/src/client/models/index.ts b/src/client/models/index.ts
new file mode 100644
index 0000000..2cb07c7
--- /dev/null
+++ b/src/client/models/index.ts
@@ -0,0 +1,271 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export * from './accessRequest';
+export * from './addIssueLabel';
+export * from './addPrLabel';
+export * from './addPrReaction';
+export * from './addReaction';
+export * from './addWorkspaceMember';
+export * from './agentCostInfo';
+export * from './agentListAllConversationsParams';
+export * from './agentListMessagesParams';
+export * from './agentRunRequest';
+export * from './agentRunResponse';
+export * from './agentSessionResponse';
+export * from './agentStepInfo';
+export * from './agentToolCallInfo';
+export * from './agentUsageInfo';
+export * from './aiAddRequest';
+export * from './aiDiscussionResponse';
+export * from './aiLikeResponse';
+export * from './aiListDiscussionsParams';
+export * from './aiListModelsParams';
+export * from './aiModelCardResponse';
+export * from './aiModelListItem';
+export * from './aiModelResponse';
+export * from './aiModelVersionResponse';
+export * from './aiProviderResponse';
+export * from './appNotificationItem';
+export * from './assignIssueUser';
+export * from './assignPrUser';
+export * from './authCaptchaParams';
+export * from './avatarUploadResponse';
+export * from './banCreateRequest';
+export * from './bindIssuePullRequest';
+export * from './bindIssueRepo';
+export * from './blameFileResponseDto';
+export * from './blobInfoResponse';
+export * from './blobLoadResponseDto';
+export * from './blobUploadBody';
+export * from './blobUploadResponseDto';
+export * from './branchAheadBehindResponseDto';
+export * from './branchInfoResponseDto';
+export * from './branchListItemDto';
+export * from './branchListResponseDto';
+export * from './branchUpstreamResponseDto';
+export * from './captchaQuery';
+export * from './captchaResponse';
+export * from './categoryCreateRequest';
+export * from './categoryUpdateRequest';
+export * from './channelListMessagesParams';
+export * from './channelMessagesAroundParams';
+export * from './channelMissedMessagesParams';
+export * from './channelSearchParams';
+export * from './cherryPickResponseDto';
+export * from './cloneRepo';
+export * from './combinedCommitStatus';
+export * from './commitBlameHunkDto';
+export * from './commitHistoryResponseDto';
+export * from './commitInfoResponseDto';
+export * from './commitMetaDto';
+export * from './commitSignatureDto';
+export * from './commitStatusResponse';
+export * from './compareCommit';
+export * from './compareResponse';
+export * from './contentResponse';
+export * from './contextMe';
+export * from './contributionHeatmapItem';
+export * from './contributionHeatmapResponse';
+export * from './contributorDto';
+export * from './conversationResponse';
+export * from './conversationWithSessionResponse';
+export * from './createAgentSession';
+export * from './createComment';
+export * from './createCommitStatus';
+export * from './createContent';
+export * from './createConversation';
+export * from './createdUserAccessToken';
+export * from './createFork';
+export * from './createIssue';
+export * from './createLabel';
+export * from './createMessageRequest';
+export * from './createMilestone';
+export * from './createPrComment';
+export * from './createProtect';
+export * from './createPrReview';
+export * from './createPrReviewComment';
+export * from './createPullRequest';
+export * from './createRelease';
+export * from './createRepo';
+export * from './createUserAccessToken';
+export * from './createUserSshKey';
+export * from './createWebhook';
+export * from './createWorkspace';
+export * from './createWorkspaceGroup';
+export * from './createWorkspaceJoinApply';
+export * from './customStatusRequest';
+export * from './diffDeltaDto';
+export * from './diffFileDto';
+export * from './diffHunkDto';
+export * from './diffLineDto';
+export * from './diffResultDto';
+export * from './diffStatsDto';
+export * from './disable2FAParams';
+export * from './dismissPrReview';
+export * from './dndRequest';
+export * from './draftSaveRequest';
+export * from './emailChangeRequest';
+export * from './emailResponse';
+export * from './emailVerifyRequest';
+export * from './enable2FAResponse';
+export * from './forkResponse';
+export * from './get2FAStatusResponse';
+export * from './gitAheadBehindParams';
+export * from './gitArchiveParams';
+export * from './gitBlameFileParams';
+export * from './gitBlobInfoParams';
+export * from './gitCherryPickBody';
+export * from './gitCommitHistoryParams';
+export * from './gitCommitWalkBody';
+export * from './gitDeleteBranchParams';
+export * from './gitDeleteContentsParams';
+export * from './gitDiffBranchesParams';
+export * from './gitDiffParams';
+export * from './gitForkBranchBody';
+export * from './gitGetContentsParams';
+export * from './gitInitTagBody';
+export * from './gitListBranchesParams';
+export * from './gitListCommitsParams';
+export * from './gitListContributorsParams';
+export * from './gitListDeliveriesParams';
+export * from './gitListForksParams';
+export * from './gitListProtectsParams';
+export * from './gitListRefsParams';
+export * from './gitListReposParams';
+export * from './gitListTagsParams';
+export * from './gitListWebhooksParams';
+export * from './gitRefResponse';
+export * from './gitTreeEntriesParams';
+export * from './gitTreeEntryByPathFromCommitParams';
+export * from './gitTreeEntryByPathParams';
+export * from './gitUpdateTagBody';
+export * from './gitWatchRepoBody';
+export * from './inviteAcceptRequest';
+export * from './inviteCreateRequest';
+export * from './issueAuthor';
+export * from './issueCommentResponse';
+export * from './issueEventResponse';
+export * from './issuePullRequestResponse';
+export * from './issueReactionResponse';
+export * from './issueRepoResponse';
+export * from './issueResponse';
+export * from './issuesListIssuesParams';
+export * from './labelResponse';
+export * from './languageStatDto';
+export * from './loginParams';
+export * from './mergePullRequest';
+export * from './messageResponse';
+export * from './milestoneResponse';
+export * from './notificationMarkAllReadRequest';
+export * from './pinRequest';
+export * from './presenceUpdateRequest';
+export * from './protectResponse';
+export * from './publicUserResponse';
+export * from './pullRequestCommentResponse';
+export * from './pullRequestListPrsParams';
+export * from './pullRequestReactionResponse';
+export * from './pullRequestResponse';
+export * from './pullRequestReviewCommentResponse';
+export * from './pullRequestReviewResponse';
+export * from './reactionRequest';
+export * from './readmeDto';
+export * from './readReceiptRequest';
+export * from './registerParams';
+export * from './releaseAssetResponse';
+export * from './releaseResponse';
+export * from './renameBranchBody';
+export * from './repoResponse';
+export * from './resetPasswordRequest';
+export * from './resetPasswordVerifyParams';
+export * from './roomCreateRequest';
+export * from './roomUpdateRequest';
+export * from './rsaResponse';
+export * from './screenShareRequest';
+export * from './searchGroupIssueHit';
+export * from './searchGroupIssueHitItemsItem';
+export * from './searchGroupRepoHit';
+export * from './searchGroupRepoHitItemsItem';
+export * from './searchGroupRoomHit';
+export * from './searchGroupRoomHitItemsItem';
+export * from './searchGroupWorkspaceHit';
+export * from './searchGroupWorkspaceHitItemsItem';
+export * from './searchParams';
+export * from './searchResponse';
+export * from './setIssueMilestone';
+export * from './tagInfoResponseDto';
+export * from './tagInitResponseDto';
+export * from './tagItemDto';
+export * from './tagListResponseDto';
+export * from './tagSummaryDto';
+export * from './tagSummaryResponseDto';
+export * from './threadCreateRequest';
+export * from './tokenRequest';
+export * from './tokenResponse';
+export * from './toolCallResponse';
+export * from './transferRepo';
+export * from './treeEntriesResponseDto';
+export * from './treeEntryByPathResponseDto';
+export * from './treeEntryDto';
+export * from './treeKindDto';
+export * from './typingAction';
+export * from './typingRequest';
+export * from './updateAgentSession';
+export * from './updateComment';
+export * from './updateContent';
+export * from './updateConversation';
+export * from './updateIssue';
+export * from './updateLabel';
+export * from './updateMessageRequest';
+export * from './updateMilestone';
+export * from './updatePrComment';
+export * from './updateProtect';
+export * from './updatePullRequest';
+export * from './updateRelease';
+export * from './updateRepo';
+export * from './updateUserAccessibilityConfig';
+export * from './updateUserAccessToken';
+export * from './updateUserAppearanceConfig';
+export * from './updateUserNotificationConfig';
+export * from './updateUserPrivacyConfig';
+export * from './updateUserProfileConfig';
+export * from './updateUserSshKey';
+export * from './updateWebhook';
+export * from './updateWorkspace';
+export * from './updateWorkspaceGroup';
+export * from './updateWorkspaceJoinStrategy';
+export * from './updateWorkspaceMember';
+export * from './userAccessibilityConfig';
+export * from './userAccessToken';
+export * from './userAppearanceConfig';
+export * from './userConfigResponse';
+export * from './userContributionHeatmapParams';
+export * from './userNotificationConfig';
+export * from './userPrivacyConfig';
+export * from './userProfileConfig';
+export * from './userRelationCard';
+export * from './userRelationCounts';
+export * from './userRelationStatus';
+export * from './usersFollowersParams';
+export * from './usersFollowingParams';
+export * from './userSshKey';
+export * from './userSummaryResponse';
+export * from './usersUserChpcParams';
+export * from './verify2FAParams';
+export * from './voiceDeafRequest';
+export * from './voiceMuteRequest';
+export * from './webhookDeliveryResponse';
+export * from './webhookResponse';
+export * from './workspaceGroupResponse';
+export * from './workspaceJoinApplyResponse';
+export * from './workspaceJoinApprovalResponse';
+export * from './workspaceJoinStrategyResponse';
+export * from './workspaceListJoinAppliesParams';
+export * from './workspaceListMembersParams';
+export * from './workspaceMemberResponse';
+export * from './workspaceResponse';
diff --git a/src/client/models/inviteAcceptRequest.ts b/src/client/models/inviteAcceptRequest.ts
new file mode 100644
index 0000000..b95cdd0
--- /dev/null
+++ b/src/client/models/inviteAcceptRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface InviteAcceptRequest {
+  code: string;
+}
diff --git a/src/client/models/inviteCreateRequest.ts b/src/client/models/inviteCreateRequest.ts
new file mode 100644
index 0000000..90592fc
--- /dev/null
+++ b/src/client/models/inviteCreateRequest.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface InviteCreateRequest {
+  /** @nullable */
+  expires_at?: string | null;
+  /** @nullable */
+  max_uses?: number | null;
+  /** @nullable */
+  room?: string | null;
+  workspace: string;
+}
diff --git a/src/client/models/issueAuthor.ts b/src/client/models/issueAuthor.ts
new file mode 100644
index 0000000..5cd61d7
--- /dev/null
+++ b/src/client/models/issueAuthor.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface IssueAuthor {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  display_name?: string | null;
+  username: string;
+}
diff --git a/src/client/models/issueCommentResponse.ts b/src/client/models/issueCommentResponse.ts
new file mode 100644
index 0000000..da1df09
--- /dev/null
+++ b/src/client/models/issueCommentResponse.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface IssueCommentResponse {
+  author: IssueAuthor;
+  body: string;
+  created_at: string;
+  id: string;
+  updated_at: string;
+}
diff --git a/src/client/models/issueEventResponse.ts b/src/client/models/issueEventResponse.ts
new file mode 100644
index 0000000..938912f
--- /dev/null
+++ b/src/client/models/issueEventResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface IssueEventResponse {
+  actor?: null | IssueAuthor;
+  created_at: string;
+  event: string;
+  /** @nullable */
+  from_value?: string | null;
+  /** @nullable */
+  to_value?: string | null;
+}
diff --git a/src/client/models/issuePullRequestResponse.ts b/src/client/models/issuePullRequestResponse.ts
new file mode 100644
index 0000000..4109f86
--- /dev/null
+++ b/src/client/models/issuePullRequestResponse.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface IssuePullRequestResponse {
+  id: string;
+  number: number;
+  state: string;
+  title: string;
+}
diff --git a/src/client/models/issueReactionResponse.ts b/src/client/models/issueReactionResponse.ts
new file mode 100644
index 0000000..fde2355
--- /dev/null
+++ b/src/client/models/issueReactionResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface IssueReactionResponse {
+  created_at: string;
+  id: string;
+  reaction: string;
+  user: IssueAuthor;
+}
diff --git a/src/client/models/issueRepoResponse.ts b/src/client/models/issueRepoResponse.ts
new file mode 100644
index 0000000..ba2ba0a
--- /dev/null
+++ b/src/client/models/issueRepoResponse.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface IssueRepoResponse {
+  id: string;
+  name: string;
+}
diff --git a/src/client/models/issueResponse.ts b/src/client/models/issueResponse.ts
new file mode 100644
index 0000000..ae138f3
--- /dev/null
+++ b/src/client/models/issueResponse.ts
@@ -0,0 +1,34 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+import type { IssuePullRequestResponse } from './issuePullRequestResponse';
+import type { IssueRepoResponse } from './issueRepoResponse';
+import type { LabelResponse } from './labelResponse';
+import type { MilestoneResponse } from './milestoneResponse';
+
+export interface IssueResponse {
+  assignees: IssueAuthor[];
+  author: IssueAuthor;
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  closed_at?: string | null;
+  closed_by?: null | IssueAuthor;
+  created_at: string;
+  /** @nullable */
+  due_at?: string | null;
+  labels: LabelResponse[];
+  milestone?: null | MilestoneResponse;
+  number: number;
+  priority: string;
+  pull_requests: IssuePullRequestResponse[];
+  repos: IssueRepoResponse[];
+  state: string;
+  title: string;
+  updated_at: string;
+}
diff --git a/src/client/models/issuesListIssuesParams.ts b/src/client/models/issuesListIssuesParams.ts
new file mode 100644
index 0000000..103abb4
--- /dev/null
+++ b/src/client/models/issuesListIssuesParams.ts
@@ -0,0 +1,40 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type IssuesListIssuesParams = {
+/**
+ * @nullable
+ */
+state?: string | null;
+/**
+ * @nullable
+ */
+label?: string | null;
+/**
+ * @nullable
+ */
+milestone?: string | null;
+/**
+ * @nullable
+ */
+assignee?: string | null;
+/**
+ * @nullable
+ */
+priority?: string | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/labelResponse.ts b/src/client/models/labelResponse.ts
new file mode 100644
index 0000000..55e6af1
--- /dev/null
+++ b/src/client/models/labelResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface LabelResponse {
+  color: string;
+  /** @nullable */
+  description?: string | null;
+  id: string;
+  name: string;
+}
diff --git a/src/client/models/languageStatDto.ts b/src/client/models/languageStatDto.ts
new file mode 100644
index 0000000..d37e0cc
--- /dev/null
+++ b/src/client/models/languageStatDto.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface LanguageStatDto {
+  bytes: number;
+  language: string;
+  percentage: number;
+}
diff --git a/src/client/models/loginParams.ts b/src/client/models/loginParams.ts
new file mode 100644
index 0000000..698da02
--- /dev/null
+++ b/src/client/models/loginParams.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface LoginParams {
+  captcha: string;
+  password: string;
+  /** @nullable */
+  totp_code?: string | null;
+  username: string;
+}
diff --git a/src/client/models/mergePullRequest.ts b/src/client/models/mergePullRequest.ts
new file mode 100644
index 0000000..4b3c098
--- /dev/null
+++ b/src/client/models/mergePullRequest.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface MergePullRequest {
+  /** @nullable */
+  commit_message?: string | null;
+  /** @nullable */
+  commit_title?: string | null;
+  /** @nullable */
+  method?: string | null;
+}
diff --git a/src/client/models/messageResponse.ts b/src/client/models/messageResponse.ts
new file mode 100644
index 0000000..c04f485
--- /dev/null
+++ b/src/client/models/messageResponse.ts
@@ -0,0 +1,28 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { ToolCallResponse } from './toolCallResponse';
+
+export interface MessageResponse {
+  /** @nullable */
+  author?: string | null;
+  content: string;
+  content_type: string;
+  conversation_id: string;
+  created_at: string;
+  id: string;
+  /** @nullable */
+  model_invocation?: string | null;
+  /** @nullable */
+  parent_id?: string | null;
+  /** @nullable */
+  reasoning_content?: string | null;
+  role: string;
+  status: string;
+  tool_calls?: ToolCallResponse[];
+  updated_at: string;
+}
diff --git a/src/client/models/milestoneResponse.ts b/src/client/models/milestoneResponse.ts
new file mode 100644
index 0000000..b3784e2
--- /dev/null
+++ b/src/client/models/milestoneResponse.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface MilestoneResponse {
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  due_at?: string | null;
+  id: string;
+  state: string;
+  title: string;
+}
diff --git a/src/client/models/notificationMarkAllReadRequest.ts b/src/client/models/notificationMarkAllReadRequest.ts
new file mode 100644
index 0000000..1409ea2
--- /dev/null
+++ b/src/client/models/notificationMarkAllReadRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface NotificationMarkAllReadRequest {
+  /** @nullable */
+  workspace_id?: string | null;
+}
diff --git a/src/client/models/pinRequest.ts b/src/client/models/pinRequest.ts
new file mode 100644
index 0000000..765ecac
--- /dev/null
+++ b/src/client/models/pinRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface PinRequest {
+  message: string;
+}
diff --git a/src/client/models/presenceUpdateRequest.ts b/src/client/models/presenceUpdateRequest.ts
new file mode 100644
index 0000000..c82ee2b
--- /dev/null
+++ b/src/client/models/presenceUpdateRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface PresenceUpdateRequest {
+  status: string;
+}
diff --git a/src/client/models/protectResponse.ts b/src/client/models/protectResponse.ts
new file mode 100644
index 0000000..aa24c05
--- /dev/null
+++ b/src/client/models/protectResponse.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ProtectResponse {
+  allow_deletions: boolean;
+  allow_force_pushes: boolean;
+  created_at: string;
+  enforce_admins: boolean;
+  id: string;
+  pattern: string;
+  repo: string;
+  require_pull_request: boolean;
+  require_status_checks: boolean;
+  required_approvals: number;
+  required_status_contexts: string[];
+  updated_at: string;
+}
diff --git a/src/client/models/publicUserResponse.ts b/src/client/models/publicUserResponse.ts
new file mode 100644
index 0000000..4ac4c64
--- /dev/null
+++ b/src/client/models/publicUserResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface PublicUserResponse {
+  allow_direct_messages: boolean;
+  avatar_url: string;
+  display_name: string;
+  language: string;
+  show_online_status: boolean;
+  timezone: string;
+  username: string;
+  website_url: string;
+}
diff --git a/src/client/models/pullRequestCommentResponse.ts b/src/client/models/pullRequestCommentResponse.ts
new file mode 100644
index 0000000..d5f654b
--- /dev/null
+++ b/src/client/models/pullRequestCommentResponse.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface PullRequestCommentResponse {
+  author: IssueAuthor;
+  body: string;
+  created_at: string;
+  id: string;
+  updated_at: string;
+}
diff --git a/src/client/models/pullRequestListPrsParams.ts b/src/client/models/pullRequestListPrsParams.ts
new file mode 100644
index 0000000..c4c198a
--- /dev/null
+++ b/src/client/models/pullRequestListPrsParams.ts
@@ -0,0 +1,36 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type PullRequestListPrsParams = {
+/**
+ * @nullable
+ */
+state?: string | null;
+/**
+ * @nullable
+ */
+author?: string | null;
+/**
+ * @nullable
+ */
+assignee?: string | null;
+/**
+ * @nullable
+ */
+label?: string | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/pullRequestReactionResponse.ts b/src/client/models/pullRequestReactionResponse.ts
new file mode 100644
index 0000000..89f75da
--- /dev/null
+++ b/src/client/models/pullRequestReactionResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface PullRequestReactionResponse {
+  created_at: string;
+  id: string;
+  reaction: string;
+  user: IssueAuthor;
+}
diff --git a/src/client/models/pullRequestResponse.ts b/src/client/models/pullRequestResponse.ts
new file mode 100644
index 0000000..0afbc2b
--- /dev/null
+++ b/src/client/models/pullRequestResponse.ts
@@ -0,0 +1,36 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+import type { LabelResponse } from './labelResponse';
+import type { PullRequestReviewResponse } from './pullRequestReviewResponse';
+
+export interface PullRequestResponse {
+  assignees: IssueAuthor[];
+  author: IssueAuthor;
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  closed_at?: string | null;
+  closed_by?: null | IssueAuthor;
+  created_at: string;
+  draft: boolean;
+  labels: LabelResponse[];
+  /** @nullable */
+  merged_at?: string | null;
+  merged_by?: null | IssueAuthor;
+  number: number;
+  reviews: PullRequestReviewResponse[];
+  source_branch: string;
+  source_repo: string;
+  source_sha: string;
+  state: string;
+  target_branch: string;
+  target_sha: string;
+  title: string;
+  updated_at: string;
+}
diff --git a/src/client/models/pullRequestReviewCommentResponse.ts b/src/client/models/pullRequestReviewCommentResponse.ts
new file mode 100644
index 0000000..b87a309
--- /dev/null
+++ b/src/client/models/pullRequestReviewCommentResponse.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface PullRequestReviewCommentResponse {
+  author: IssueAuthor;
+  body: string;
+  commit_sha: string;
+  created_at: string;
+  id: string;
+  /** @nullable */
+  line?: number | null;
+  path: string;
+  resolved: boolean;
+  updated_at: string;
+}
diff --git a/src/client/models/pullRequestReviewResponse.ts b/src/client/models/pullRequestReviewResponse.ts
new file mode 100644
index 0000000..2b3512d
--- /dev/null
+++ b/src/client/models/pullRequestReviewResponse.ts
@@ -0,0 +1,21 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { IssueAuthor } from './issueAuthor';
+
+export interface PullRequestReviewResponse {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  commit_sha?: string | null;
+  created_at: string;
+  id: string;
+  reviewer: IssueAuthor;
+  state: string;
+  /** @nullable */
+  submitted_at?: string | null;
+}
diff --git a/src/client/models/reactionRequest.ts b/src/client/models/reactionRequest.ts
new file mode 100644
index 0000000..8a162c6
--- /dev/null
+++ b/src/client/models/reactionRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ReactionRequest {
+  emoji: string;
+  message: string;
+}
diff --git a/src/client/models/readReceiptRequest.ts b/src/client/models/readReceiptRequest.ts
new file mode 100644
index 0000000..966b4b8
--- /dev/null
+++ b/src/client/models/readReceiptRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ReadReceiptRequest {
+  last_read_seq: number;
+}
diff --git a/src/client/models/readmeDto.ts b/src/client/models/readmeDto.ts
new file mode 100644
index 0000000..5d97012
--- /dev/null
+++ b/src/client/models/readmeDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ReadmeDto {
+  content: string;
+  html: string;
+}
diff --git a/src/client/models/registerParams.ts b/src/client/models/registerParams.ts
new file mode 100644
index 0000000..082bf47
--- /dev/null
+++ b/src/client/models/registerParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface RegisterParams {
+  captcha: string;
+  email: string;
+  password: string;
+  username: string;
+}
diff --git a/src/client/models/releaseAssetResponse.ts b/src/client/models/releaseAssetResponse.ts
new file mode 100644
index 0000000..2e618da
--- /dev/null
+++ b/src/client/models/releaseAssetResponse.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ReleaseAssetResponse {
+  /** @nullable */
+  content_type?: string | null;
+  created_at: string;
+  download_count: number;
+  id: string;
+  name: string;
+  size: number;
+}
diff --git a/src/client/models/releaseResponse.ts b/src/client/models/releaseResponse.ts
new file mode 100644
index 0000000..380b7ab
--- /dev/null
+++ b/src/client/models/releaseResponse.ts
@@ -0,0 +1,24 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { ReleaseAssetResponse } from './releaseAssetResponse';
+
+export interface ReleaseResponse {
+  assets: ReleaseAssetResponse[];
+  author: string;
+  /** @nullable */
+  body?: string | null;
+  created_at: string;
+  draft: boolean;
+  id: string;
+  name: string;
+  prerelease: boolean;
+  /** @nullable */
+  published_at?: string | null;
+  tag_name: string;
+  target_commit_sha: string;
+}
diff --git a/src/client/models/renameBranchBody.ts b/src/client/models/renameBranchBody.ts
new file mode 100644
index 0000000..391023d
--- /dev/null
+++ b/src/client/models/renameBranchBody.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface RenameBranchBody {
+  force?: boolean;
+  new_branch: string;
+}
diff --git a/src/client/models/repoResponse.ts b/src/client/models/repoResponse.ts
new file mode 100644
index 0000000..be0a11f
--- /dev/null
+++ b/src/client/models/repoResponse.ts
@@ -0,0 +1,23 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface RepoResponse {
+  created_at: string;
+  created_by: string;
+  default_branch: string;
+  /** @nullable */
+  description?: string | null;
+  id: string;
+  is_archived: boolean;
+  is_mirror: boolean;
+  is_template: boolean;
+  name: string;
+  size_bytes: number;
+  updated_at: string;
+  visibility: string;
+}
diff --git a/src/client/models/resetPasswordRequest.ts b/src/client/models/resetPasswordRequest.ts
new file mode 100644
index 0000000..8e735c4
--- /dev/null
+++ b/src/client/models/resetPasswordRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ResetPasswordRequest {
+  email: string;
+}
diff --git a/src/client/models/resetPasswordVerifyParams.ts b/src/client/models/resetPasswordVerifyParams.ts
new file mode 100644
index 0000000..65b4dd2
--- /dev/null
+++ b/src/client/models/resetPasswordVerifyParams.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ResetPasswordVerifyParams {
+  password: string;
+  token: string;
+}
diff --git a/src/client/models/roomCreateRequest.ts b/src/client/models/roomCreateRequest.ts
new file mode 100644
index 0000000..7e5bc7a
--- /dev/null
+++ b/src/client/models/roomCreateRequest.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface RoomCreateRequest {
+  /** @nullable */
+  category?: string | null;
+  public: boolean;
+  room_name: string;
+  workspace: string;
+}
diff --git a/src/client/models/roomUpdateRequest.ts b/src/client/models/roomUpdateRequest.ts
new file mode 100644
index 0000000..ca3ff9a
--- /dev/null
+++ b/src/client/models/roomUpdateRequest.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface RoomUpdateRequest {
+  /** @nullable */
+  category?: string | null;
+  /** @nullable */
+  public?: boolean | null;
+  /** @nullable */
+  room_name?: string | null;
+}
diff --git a/src/client/models/rsaResponse.ts b/src/client/models/rsaResponse.ts
new file mode 100644
index 0000000..87609f9
--- /dev/null
+++ b/src/client/models/rsaResponse.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface RsaResponse {
+  public_key: string;
+}
diff --git a/src/client/models/screenShareRequest.ts b/src/client/models/screenShareRequest.ts
new file mode 100644
index 0000000..cbb212a
--- /dev/null
+++ b/src/client/models/screenShareRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ScreenShareRequest {
+  start: boolean;
+}
diff --git a/src/client/models/searchGroupIssueHit.ts b/src/client/models/searchGroupIssueHit.ts
new file mode 100644
index 0000000..8d4f088
--- /dev/null
+++ b/src/client/models/searchGroupIssueHit.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { SearchGroupIssueHitItemsItem } from './searchGroupIssueHitItemsItem';
+
+export interface SearchGroupIssueHit {
+  has_more: boolean;
+  items: SearchGroupIssueHitItemsItem[];
+  /** @minimum 0 */
+  total: number;
+}
diff --git a/src/client/models/searchGroupIssueHitItemsItem.ts b/src/client/models/searchGroupIssueHitItemsItem.ts
new file mode 100644
index 0000000..b0cfcab
--- /dev/null
+++ b/src/client/models/searchGroupIssueHitItemsItem.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type SearchGroupIssueHitItemsItem = {
+  number: number;
+  state: string;
+  title: string;
+  workspace: string;
+};
diff --git a/src/client/models/searchGroupRepoHit.ts b/src/client/models/searchGroupRepoHit.ts
new file mode 100644
index 0000000..bc5d5cb
--- /dev/null
+++ b/src/client/models/searchGroupRepoHit.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { SearchGroupRepoHitItemsItem } from './searchGroupRepoHitItemsItem';
+
+export interface SearchGroupRepoHit {
+  has_more: boolean;
+  items: SearchGroupRepoHitItemsItem[];
+  /** @minimum 0 */
+  total: number;
+}
diff --git a/src/client/models/searchGroupRepoHitItemsItem.ts b/src/client/models/searchGroupRepoHitItemsItem.ts
new file mode 100644
index 0000000..0c118d8
--- /dev/null
+++ b/src/client/models/searchGroupRepoHitItemsItem.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type SearchGroupRepoHitItemsItem = {
+  /** @nullable */
+  description?: string | null;
+  name: string;
+  workspace: string;
+};
diff --git a/src/client/models/searchGroupRoomHit.ts b/src/client/models/searchGroupRoomHit.ts
new file mode 100644
index 0000000..127336a
--- /dev/null
+++ b/src/client/models/searchGroupRoomHit.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { SearchGroupRoomHitItemsItem } from './searchGroupRoomHitItemsItem';
+
+export interface SearchGroupRoomHit {
+  has_more: boolean;
+  items: SearchGroupRoomHitItemsItem[];
+  /** @minimum 0 */
+  total: number;
+}
diff --git a/src/client/models/searchGroupRoomHitItemsItem.ts b/src/client/models/searchGroupRoomHitItemsItem.ts
new file mode 100644
index 0000000..a85889b
--- /dev/null
+++ b/src/client/models/searchGroupRoomHitItemsItem.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type SearchGroupRoomHitItemsItem = {
+  id: string;
+  name: string;
+  workspace: string;
+};
diff --git a/src/client/models/searchGroupWorkspaceHit.ts b/src/client/models/searchGroupWorkspaceHit.ts
new file mode 100644
index 0000000..e5bf225
--- /dev/null
+++ b/src/client/models/searchGroupWorkspaceHit.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { SearchGroupWorkspaceHitItemsItem } from './searchGroupWorkspaceHitItemsItem';
+
+export interface SearchGroupWorkspaceHit {
+  has_more: boolean;
+  items: SearchGroupWorkspaceHitItemsItem[];
+  /** @minimum 0 */
+  total: number;
+}
diff --git a/src/client/models/searchGroupWorkspaceHitItemsItem.ts b/src/client/models/searchGroupWorkspaceHitItemsItem.ts
new file mode 100644
index 0000000..83c2820
--- /dev/null
+++ b/src/client/models/searchGroupWorkspaceHitItemsItem.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type SearchGroupWorkspaceHitItemsItem = {
+  /** @nullable */
+  description?: string | null;
+  name: string;
+};
diff --git a/src/client/models/searchParams.ts b/src/client/models/searchParams.ts
new file mode 100644
index 0000000..6a13e74
--- /dev/null
+++ b/src/client/models/searchParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type SearchParams = {
+/**
+ * @nullable
+ */
+q?: string | null;
+};
diff --git a/src/client/models/searchResponse.ts b/src/client/models/searchResponse.ts
new file mode 100644
index 0000000..47b8f0a
--- /dev/null
+++ b/src/client/models/searchResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { SearchGroupIssueHit } from './searchGroupIssueHit';
+import type { SearchGroupRepoHit } from './searchGroupRepoHit';
+import type { SearchGroupRoomHit } from './searchGroupRoomHit';
+import type { SearchGroupWorkspaceHit } from './searchGroupWorkspaceHit';
+
+export interface SearchResponse {
+  issues: SearchGroupIssueHit;
+  repos: SearchGroupRepoHit;
+  rooms: SearchGroupRoomHit;
+  workspaces: SearchGroupWorkspaceHit;
+}
diff --git a/src/client/models/setIssueMilestone.ts b/src/client/models/setIssueMilestone.ts
new file mode 100644
index 0000000..170c993
--- /dev/null
+++ b/src/client/models/setIssueMilestone.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface SetIssueMilestone {
+  milestone_id: string;
+}
diff --git a/src/client/models/tagInfoResponseDto.ts b/src/client/models/tagInfoResponseDto.ts
new file mode 100644
index 0000000..b6a1d2b
--- /dev/null
+++ b/src/client/models/tagInfoResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TagItemDto } from './tagItemDto';
+
+export interface TagInfoResponseDto {
+  tag?: null | TagItemDto;
+}
diff --git a/src/client/models/tagInitResponseDto.ts b/src/client/models/tagInitResponseDto.ts
new file mode 100644
index 0000000..c925e60
--- /dev/null
+++ b/src/client/models/tagInitResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface TagInitResponseDto {
+  /** @nullable */
+  oid?: string | null;
+}
diff --git a/src/client/models/tagItemDto.ts b/src/client/models/tagItemDto.ts
new file mode 100644
index 0000000..faa00f4
--- /dev/null
+++ b/src/client/models/tagItemDto.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface TagItemDto {
+  is_annotated: boolean;
+  /** @nullable */
+  message?: string | null;
+  name: string;
+  oid: string;
+  /** @nullable */
+  tagger?: string | null;
+  /** @nullable */
+  tagger_email?: string | null;
+  target: string;
+}
diff --git a/src/client/models/tagListResponseDto.ts b/src/client/models/tagListResponseDto.ts
new file mode 100644
index 0000000..7e09d82
--- /dev/null
+++ b/src/client/models/tagListResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TagItemDto } from './tagItemDto';
+
+export interface TagListResponseDto {
+  tags: TagItemDto[];
+}
diff --git a/src/client/models/tagSummaryDto.ts b/src/client/models/tagSummaryDto.ts
new file mode 100644
index 0000000..c449c3c
--- /dev/null
+++ b/src/client/models/tagSummaryDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface TagSummaryDto {
+  /** @minimum 0 */
+  total_count: number;
+}
diff --git a/src/client/models/tagSummaryResponseDto.ts b/src/client/models/tagSummaryResponseDto.ts
new file mode 100644
index 0000000..831cb56
--- /dev/null
+++ b/src/client/models/tagSummaryResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TagSummaryDto } from './tagSummaryDto';
+
+export interface TagSummaryResponseDto {
+  summary?: null | TagSummaryDto;
+}
diff --git a/src/client/models/threadCreateRequest.ts b/src/client/models/threadCreateRequest.ts
new file mode 100644
index 0000000..05098ee
--- /dev/null
+++ b/src/client/models/threadCreateRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ThreadCreateRequest {
+  parent: number;
+}
diff --git a/src/client/models/tokenRequest.ts b/src/client/models/tokenRequest.ts
new file mode 100644
index 0000000..a67aa14
--- /dev/null
+++ b/src/client/models/tokenRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface TokenRequest {
+  client_id: string;
+  device_id: string;
+}
diff --git a/src/client/models/tokenResponse.ts b/src/client/models/tokenResponse.ts
new file mode 100644
index 0000000..de02d72
--- /dev/null
+++ b/src/client/models/tokenResponse.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface TokenResponse {
+  access_token: string;
+  /** @minimum 0 */
+  expires_in_secs: number;
+}
diff --git a/src/client/models/toolCallResponse.ts b/src/client/models/toolCallResponse.ts
new file mode 100644
index 0000000..f4c61e9
--- /dev/null
+++ b/src/client/models/toolCallResponse.ts
@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface ToolCallResponse {
+  arguments: unknown;
+  /** @nullable */
+  elapsed_ms?: number | null;
+  /** @nullable */
+  error?: string | null;
+  id: string;
+  name: string;
+  output?: unknown;
+  status: string;
+}
diff --git a/src/client/models/transferRepo.ts b/src/client/models/transferRepo.ts
new file mode 100644
index 0000000..95ab3c6
--- /dev/null
+++ b/src/client/models/transferRepo.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface TransferRepo {
+  target_workspace: string;
+}
diff --git a/src/client/models/treeEntriesResponseDto.ts b/src/client/models/treeEntriesResponseDto.ts
new file mode 100644
index 0000000..33049b4
--- /dev/null
+++ b/src/client/models/treeEntriesResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TreeEntryDto } from './treeEntryDto';
+
+export interface TreeEntriesResponseDto {
+  entries: TreeEntryDto[];
+}
diff --git a/src/client/models/treeEntryByPathResponseDto.ts b/src/client/models/treeEntryByPathResponseDto.ts
new file mode 100644
index 0000000..20e3b06
--- /dev/null
+++ b/src/client/models/treeEntryByPathResponseDto.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TreeEntryDto } from './treeEntryDto';
+
+export interface TreeEntryByPathResponseDto {
+  entry?: null | TreeEntryDto;
+}
diff --git a/src/client/models/treeEntryDto.ts b/src/client/models/treeEntryDto.ts
new file mode 100644
index 0000000..c81ef57
--- /dev/null
+++ b/src/client/models/treeEntryDto.ts
@@ -0,0 +1,26 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TreeKindDto } from './treeKindDto';
+
+export interface TreeEntryDto {
+  /** @minimum 0 */
+  filemode: number;
+  is_binary: boolean;
+  is_lfs: boolean;
+  kind: TreeKindDto;
+  /** @nullable */
+  last_commit_author_email?: string | null;
+  /** @nullable */
+  last_commit_author_name?: string | null;
+  /** @nullable */
+  last_commit_message?: string | null;
+  /** @nullable */
+  last_commit_time?: string | null;
+  name: string;
+  oid: string;
+}
diff --git a/src/client/models/treeKindDto.ts b/src/client/models/treeKindDto.ts
new file mode 100644
index 0000000..40021a7
--- /dev/null
+++ b/src/client/models/treeKindDto.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type TreeKindDto = typeof TreeKindDto[keyof typeof TreeKindDto];
+
+
+export const TreeKindDto = {
+  blob: 'blob',
+  tree: 'tree',
+  lfs_pointer: 'lfs_pointer',
+} as const;
diff --git a/src/client/models/typingAction.ts b/src/client/models/typingAction.ts
new file mode 100644
index 0000000..8d63b9f
--- /dev/null
+++ b/src/client/models/typingAction.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type TypingAction = typeof TypingAction[keyof typeof TypingAction];
+
+
+export const TypingAction = {
+  Start: 'Start',
+  Stop: 'Stop',
+} as const;
diff --git a/src/client/models/typingRequest.ts b/src/client/models/typingRequest.ts
new file mode 100644
index 0000000..e7dcdba
--- /dev/null
+++ b/src/client/models/typingRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { TypingAction } from './typingAction';
+
+export interface TypingRequest {
+  action: TypingAction;
+}
diff --git a/src/client/models/updateAgentSession.ts b/src/client/models/updateAgentSession.ts
new file mode 100644
index 0000000..bb8ff91
--- /dev/null
+++ b/src/client/models/updateAgentSession.ts
@@ -0,0 +1,40 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateAgentSession {
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  enabled?: boolean | null;
+  /** @nullable */
+  iteration_budget?: number | null;
+  /** @nullable */
+  knowledge_base_ids?: string[] | null;
+  /** @nullable */
+  max_output_tokens?: number | null;
+  /** @nullable */
+  memory_provider?: string | null;
+  /** @nullable */
+  memory_provider_config?: string | null;
+  /** @nullable */
+  model_version?: string | null;
+  /** @nullable */
+  name?: string | null;
+  /** @nullable */
+  system_prompt?: string | null;
+  /** @nullable */
+  temperature?: number | null;
+  /** @nullable */
+  tool_policy?: string | null;
+  /** @nullable */
+  toolset_json?: string | null;
+  /** @nullable */
+  variables?: string | null;
+  /** @nullable */
+  visibility?: string | null;
+}
diff --git a/src/client/models/updateComment.ts b/src/client/models/updateComment.ts
new file mode 100644
index 0000000..b92a396
--- /dev/null
+++ b/src/client/models/updateComment.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateComment {
+  body: string;
+}
diff --git a/src/client/models/updateContent.ts b/src/client/models/updateContent.ts
new file mode 100644
index 0000000..77d0b58
--- /dev/null
+++ b/src/client/models/updateContent.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateContent {
+  /** @nullable */
+  branch?: string | null;
+  content: string;
+  message: string;
+  sha: string;
+}
diff --git a/src/client/models/updateConversation.ts b/src/client/models/updateConversation.ts
new file mode 100644
index 0000000..0a90cbd
--- /dev/null
+++ b/src/client/models/updateConversation.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateConversation {
+  /** @nullable */
+  title?: string | null;
+}
diff --git a/src/client/models/updateIssue.ts b/src/client/models/updateIssue.ts
new file mode 100644
index 0000000..234e605
--- /dev/null
+++ b/src/client/models/updateIssue.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateIssue {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  due_at?: string | null;
+  /** @nullable */
+  priority?: string | null;
+  /** @nullable */
+  title?: string | null;
+}
diff --git a/src/client/models/updateLabel.ts b/src/client/models/updateLabel.ts
new file mode 100644
index 0000000..a3465a3
--- /dev/null
+++ b/src/client/models/updateLabel.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateLabel {
+  /** @nullable */
+  color?: string | null;
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  name?: string | null;
+}
diff --git a/src/client/models/updateMessageRequest.ts b/src/client/models/updateMessageRequest.ts
new file mode 100644
index 0000000..edab0d9
--- /dev/null
+++ b/src/client/models/updateMessageRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateMessageRequest {
+  content: string;
+}
diff --git a/src/client/models/updateMilestone.ts b/src/client/models/updateMilestone.ts
new file mode 100644
index 0000000..29a8a49
--- /dev/null
+++ b/src/client/models/updateMilestone.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateMilestone {
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  due_at?: string | null;
+  /** @nullable */
+  state?: string | null;
+  /** @nullable */
+  title?: string | null;
+}
diff --git a/src/client/models/updatePrComment.ts b/src/client/models/updatePrComment.ts
new file mode 100644
index 0000000..5a5c8a3
--- /dev/null
+++ b/src/client/models/updatePrComment.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdatePrComment {
+  body: string;
+}
diff --git a/src/client/models/updateProtect.ts b/src/client/models/updateProtect.ts
new file mode 100644
index 0000000..b625e74
--- /dev/null
+++ b/src/client/models/updateProtect.ts
@@ -0,0 +1,26 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateProtect {
+  /** @nullable */
+  allow_deletions?: boolean | null;
+  /** @nullable */
+  allow_force_pushes?: boolean | null;
+  /** @nullable */
+  enforce_admins?: boolean | null;
+  /** @nullable */
+  pattern?: string | null;
+  /** @nullable */
+  require_pull_request?: boolean | null;
+  /** @nullable */
+  require_status_checks?: boolean | null;
+  /** @nullable */
+  required_approvals?: number | null;
+  /** @nullable */
+  required_status_contexts?: string[] | null;
+}
diff --git a/src/client/models/updatePullRequest.ts b/src/client/models/updatePullRequest.ts
new file mode 100644
index 0000000..9fc0838
--- /dev/null
+++ b/src/client/models/updatePullRequest.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdatePullRequest {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  draft?: boolean | null;
+  /** @nullable */
+  state?: string | null;
+  /** @nullable */
+  title?: string | null;
+}
diff --git a/src/client/models/updateRelease.ts b/src/client/models/updateRelease.ts
new file mode 100644
index 0000000..749015d
--- /dev/null
+++ b/src/client/models/updateRelease.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateRelease {
+  /** @nullable */
+  body?: string | null;
+  /** @nullable */
+  draft?: boolean | null;
+  /** @nullable */
+  name?: string | null;
+  /** @nullable */
+  prerelease?: boolean | null;
+  /** @nullable */
+  tag_name?: string | null;
+}
diff --git a/src/client/models/updateRepo.ts b/src/client/models/updateRepo.ts
new file mode 100644
index 0000000..8f0edef
--- /dev/null
+++ b/src/client/models/updateRepo.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateRepo {
+  /** @nullable */
+  default_branch?: string | null;
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  is_archived?: boolean | null;
+  /** @nullable */
+  is_template?: boolean | null;
+  /** @nullable */
+  name?: string | null;
+  /** @nullable */
+  visibility?: string | null;
+}
diff --git a/src/client/models/updateUserAccessToken.ts b/src/client/models/updateUserAccessToken.ts
new file mode 100644
index 0000000..1ce1c66
--- /dev/null
+++ b/src/client/models/updateUserAccessToken.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserAccessToken {
+  /** @nullable */
+  expires_at?: string | null;
+  /** @nullable */
+  name?: string | null;
+  /** @nullable */
+  scopes?: string[] | null;
+}
diff --git a/src/client/models/updateUserAccessibilityConfig.ts b/src/client/models/updateUserAccessibilityConfig.ts
new file mode 100644
index 0000000..e778168
--- /dev/null
+++ b/src/client/models/updateUserAccessibilityConfig.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserAccessibilityConfig {
+  /** @nullable */
+  color_blind_mode?: string | null;
+  /** @nullable */
+  font_scale_percent?: number | null;
+  /** @nullable */
+  high_contrast?: boolean | null;
+  /** @nullable */
+  reduce_motion?: boolean | null;
+  /** @nullable */
+  screen_reader_optimized?: boolean | null;
+}
diff --git a/src/client/models/updateUserAppearanceConfig.ts b/src/client/models/updateUserAppearanceConfig.ts
new file mode 100644
index 0000000..c4c35dd
--- /dev/null
+++ b/src/client/models/updateUserAppearanceConfig.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserAppearanceConfig {
+  /** @nullable */
+  code_theme?: string | null;
+  /** @nullable */
+  layout_density?: string | null;
+  /** @nullable */
+  show_line_numbers?: boolean | null;
+  /** @nullable */
+  sidebar_collapsed?: boolean | null;
+  /** @nullable */
+  theme?: string | null;
+}
diff --git a/src/client/models/updateUserNotificationConfig.ts b/src/client/models/updateUserNotificationConfig.ts
new file mode 100644
index 0000000..da26014
--- /dev/null
+++ b/src/client/models/updateUserNotificationConfig.ts
@@ -0,0 +1,36 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserNotificationConfig {
+  /** @nullable */
+  digest_mode?: string | null;
+  /** @nullable */
+  dnd_enabled?: boolean | null;
+  /** @nullable */
+  dnd_end_minute?: number | null;
+  /** @nullable */
+  dnd_start_minute?: number | null;
+  /** @nullable */
+  email_enabled?: boolean | null;
+  /** @nullable */
+  in_app_enabled?: boolean | null;
+  /** @nullable */
+  marketing_enabled?: boolean | null;
+  /** @nullable */
+  product_enabled?: boolean | null;
+  /** @nullable */
+  push_enabled?: boolean | null;
+  /** @nullable */
+  push_subscription_endpoint?: string | null;
+  /** @nullable */
+  push_subscription_keys_auth?: string | null;
+  /** @nullable */
+  push_subscription_keys_p256dh?: string | null;
+  /** @nullable */
+  security_enabled?: boolean | null;
+}
diff --git a/src/client/models/updateUserPrivacyConfig.ts b/src/client/models/updateUserPrivacyConfig.ts
new file mode 100644
index 0000000..dc44e14
--- /dev/null
+++ b/src/client/models/updateUserPrivacyConfig.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserPrivacyConfig {
+  /** @nullable */
+  activity_visibility?: string | null;
+  /** @nullable */
+  allow_direct_messages?: boolean | null;
+  /** @nullable */
+  allow_search_indexing?: boolean | null;
+  /** @nullable */
+  email_visibility?: string | null;
+  /** @nullable */
+  profile_visibility?: string | null;
+  /** @nullable */
+  show_online_status?: boolean | null;
+}
diff --git a/src/client/models/updateUserProfileConfig.ts b/src/client/models/updateUserProfileConfig.ts
new file mode 100644
index 0000000..4ecd8b6
--- /dev/null
+++ b/src/client/models/updateUserProfileConfig.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserProfileConfig {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  language?: string | null;
+  /** @nullable */
+  theme?: string | null;
+  /** @nullable */
+  timezone?: string | null;
+}
diff --git a/src/client/models/updateUserSshKey.ts b/src/client/models/updateUserSshKey.ts
new file mode 100644
index 0000000..b35597b
--- /dev/null
+++ b/src/client/models/updateUserSshKey.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateUserSshKey {
+  /** @nullable */
+  expires_at?: string | null;
+  /** @nullable */
+  title?: string | null;
+}
diff --git a/src/client/models/updateWebhook.ts b/src/client/models/updateWebhook.ts
new file mode 100644
index 0000000..6b222d9
--- /dev/null
+++ b/src/client/models/updateWebhook.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateWebhook {
+  /** @nullable */
+  active?: boolean | null;
+  /** @nullable */
+  events?: string[] | null;
+  /** @nullable */
+  secret?: string | null;
+  /** @nullable */
+  url?: string | null;
+}
diff --git a/src/client/models/updateWorkspace.ts b/src/client/models/updateWorkspace.ts
new file mode 100644
index 0000000..8f87434
--- /dev/null
+++ b/src/client/models/updateWorkspace.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateWorkspace {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  description?: string | null;
+  /** @nullable */
+  name?: string | null;
+}
diff --git a/src/client/models/updateWorkspaceGroup.ts b/src/client/models/updateWorkspaceGroup.ts
new file mode 100644
index 0000000..52e05b5
--- /dev/null
+++ b/src/client/models/updateWorkspaceGroup.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateWorkspaceGroup {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  name?: string | null;
+}
diff --git a/src/client/models/updateWorkspaceJoinStrategy.ts b/src/client/models/updateWorkspaceJoinStrategy.ts
new file mode 100644
index 0000000..2b5ed17
--- /dev/null
+++ b/src/client/models/updateWorkspaceJoinStrategy.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateWorkspaceJoinStrategy {
+  /** @nullable */
+  answer?: string | null;
+  /** @nullable */
+  enabled?: boolean | null;
+  /** @nullable */
+  question?: string | null;
+  /** @nullable */
+  require_approval?: boolean | null;
+  /** @nullable */
+  require_question?: boolean | null;
+}
diff --git a/src/client/models/updateWorkspaceMember.ts b/src/client/models/updateWorkspaceMember.ts
new file mode 100644
index 0000000..77a994c
--- /dev/null
+++ b/src/client/models/updateWorkspaceMember.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UpdateWorkspaceMember {
+  admin: boolean;
+}
diff --git a/src/client/models/userAccessToken.ts b/src/client/models/userAccessToken.ts
new file mode 100644
index 0000000..ec1bbed
--- /dev/null
+++ b/src/client/models/userAccessToken.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserAccessToken {
+  created_at: string;
+  /** @nullable */
+  expires_at?: string | null;
+  id: number;
+  is_revoked: boolean;
+  name: string;
+  scopes: string[];
+  updated_at: string;
+}
diff --git a/src/client/models/userAccessibilityConfig.ts b/src/client/models/userAccessibilityConfig.ts
new file mode 100644
index 0000000..89247d0
--- /dev/null
+++ b/src/client/models/userAccessibilityConfig.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserAccessibilityConfig {
+  /** @nullable */
+  color_blind_mode?: string | null;
+  font_scale_percent: number;
+  high_contrast: boolean;
+  reduce_motion: boolean;
+  screen_reader_optimized: boolean;
+}
diff --git a/src/client/models/userAppearanceConfig.ts b/src/client/models/userAppearanceConfig.ts
new file mode 100644
index 0000000..ceb1be6
--- /dev/null
+++ b/src/client/models/userAppearanceConfig.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserAppearanceConfig {
+  code_theme: string;
+  layout_density: string;
+  show_line_numbers: boolean;
+  sidebar_collapsed: boolean;
+  theme: string;
+}
diff --git a/src/client/models/userConfigResponse.ts b/src/client/models/userConfigResponse.ts
new file mode 100644
index 0000000..9a2606e
--- /dev/null
+++ b/src/client/models/userConfigResponse.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+import type { UserAccessibilityConfig } from './userAccessibilityConfig';
+import type { UserAppearanceConfig } from './userAppearanceConfig';
+import type { UserNotificationConfig } from './userNotificationConfig';
+import type { UserPrivacyConfig } from './userPrivacyConfig';
+import type { UserProfileConfig } from './userProfileConfig';
+
+export interface UserConfigResponse {
+  accessibility: UserAccessibilityConfig;
+  appearance: UserAppearanceConfig;
+  notifications: UserNotificationConfig;
+  privacy: UserPrivacyConfig;
+  profile: UserProfileConfig;
+}
diff --git a/src/client/models/userContributionHeatmapParams.ts b/src/client/models/userContributionHeatmapParams.ts
new file mode 100644
index 0000000..1bc2934
--- /dev/null
+++ b/src/client/models/userContributionHeatmapParams.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type UserContributionHeatmapParams = {
+/**
+ * @nullable
+ */
+start_date?: string | null;
+/**
+ * @nullable
+ */
+end_date?: string | null;
+};
diff --git a/src/client/models/userNotificationConfig.ts b/src/client/models/userNotificationConfig.ts
new file mode 100644
index 0000000..3b78821
--- /dev/null
+++ b/src/client/models/userNotificationConfig.ts
@@ -0,0 +1,28 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserNotificationConfig {
+  digest_mode: string;
+  dnd_enabled: boolean;
+  /** @nullable */
+  dnd_end_minute?: number | null;
+  /** @nullable */
+  dnd_start_minute?: number | null;
+  email_enabled: boolean;
+  in_app_enabled: boolean;
+  marketing_enabled: boolean;
+  product_enabled: boolean;
+  push_enabled: boolean;
+  /** @nullable */
+  push_subscription_endpoint?: string | null;
+  /** @nullable */
+  push_subscription_keys_auth?: string | null;
+  /** @nullable */
+  push_subscription_keys_p256dh?: string | null;
+  security_enabled: boolean;
+}
diff --git a/src/client/models/userPrivacyConfig.ts b/src/client/models/userPrivacyConfig.ts
new file mode 100644
index 0000000..095550a
--- /dev/null
+++ b/src/client/models/userPrivacyConfig.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserPrivacyConfig {
+  activity_visibility: string;
+  allow_direct_messages: boolean;
+  allow_search_indexing: boolean;
+  email_visibility: string;
+  profile_visibility: string;
+  show_online_status: boolean;
+}
diff --git a/src/client/models/userProfileConfig.ts b/src/client/models/userProfileConfig.ts
new file mode 100644
index 0000000..4f87cd1
--- /dev/null
+++ b/src/client/models/userProfileConfig.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserProfileConfig {
+  language: string;
+  theme: string;
+  timezone: string;
+}
diff --git a/src/client/models/userRelationCard.ts b/src/client/models/userRelationCard.ts
new file mode 100644
index 0000000..68f6936
--- /dev/null
+++ b/src/client/models/userRelationCard.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserRelationCard {
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  display_name?: string | null;
+  is_blocked: boolean;
+  is_following: boolean;
+  username: string;
+}
diff --git a/src/client/models/userRelationCounts.ts b/src/client/models/userRelationCounts.ts
new file mode 100644
index 0000000..1c3ddfb
--- /dev/null
+++ b/src/client/models/userRelationCounts.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserRelationCounts {
+  blocked: number;
+  followers: number;
+  following: number;
+}
diff --git a/src/client/models/userRelationStatus.ts b/src/client/models/userRelationStatus.ts
new file mode 100644
index 0000000..3ee4d09
--- /dev/null
+++ b/src/client/models/userRelationStatus.ts
@@ -0,0 +1,17 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserRelationStatus {
+  /** @nullable */
+  avatar_url?: string | null;
+  has_blocked_me: boolean;
+  is_blocked: boolean;
+  is_followed_by: boolean;
+  is_following: boolean;
+  username: string;
+}
diff --git a/src/client/models/userSshKey.ts b/src/client/models/userSshKey.ts
new file mode 100644
index 0000000..1408c62
--- /dev/null
+++ b/src/client/models/userSshKey.ts
@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserSshKey {
+  created_at: string;
+  /** @nullable */
+  expires_at?: string | null;
+  fingerprint: string;
+  id: number;
+  is_revoked: boolean;
+  is_verified: boolean;
+  /** @nullable */
+  key_bits?: number | null;
+  key_type: string;
+  /** @nullable */
+  last_used_at?: string | null;
+  public_key: string;
+  title: string;
+  updated_at: string;
+}
diff --git a/src/client/models/userSummaryResponse.ts b/src/client/models/userSummaryResponse.ts
new file mode 100644
index 0000000..0f8120c
--- /dev/null
+++ b/src/client/models/userSummaryResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface UserSummaryResponse {
+  avatar_url: string;
+  created_at: string;
+  display_name: string;
+  username: string;
+  website_url: string;
+}
diff --git a/src/client/models/usersFollowersParams.ts b/src/client/models/usersFollowersParams.ts
new file mode 100644
index 0000000..a2ec999
--- /dev/null
+++ b/src/client/models/usersFollowersParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type UsersFollowersParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/usersFollowingParams.ts b/src/client/models/usersFollowingParams.ts
new file mode 100644
index 0000000..3b97318
--- /dev/null
+++ b/src/client/models/usersFollowingParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type UsersFollowingParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/usersUserChpcParams.ts b/src/client/models/usersUserChpcParams.ts
new file mode 100644
index 0000000..f7941c6
--- /dev/null
+++ b/src/client/models/usersUserChpcParams.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type UsersUserChpcParams = {
+/**
+ * @nullable
+ */
+start_date?: string | null;
+/**
+ * @nullable
+ */
+end_date?: string | null;
+};
diff --git a/src/client/models/verify2FAParams.ts b/src/client/models/verify2FAParams.ts
new file mode 100644
index 0000000..efaceb1
--- /dev/null
+++ b/src/client/models/verify2FAParams.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface Verify2FAParams {
+  code: string;
+}
diff --git a/src/client/models/voiceDeafRequest.ts b/src/client/models/voiceDeafRequest.ts
new file mode 100644
index 0000000..3b037a3
--- /dev/null
+++ b/src/client/models/voiceDeafRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface VoiceDeafRequest {
+  deafened: boolean;
+}
diff --git a/src/client/models/voiceMuteRequest.ts b/src/client/models/voiceMuteRequest.ts
new file mode 100644
index 0000000..bc7d3bd
--- /dev/null
+++ b/src/client/models/voiceMuteRequest.ts
@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface VoiceMuteRequest {
+  muted: boolean;
+}
diff --git a/src/client/models/webhookDeliveryResponse.ts b/src/client/models/webhookDeliveryResponse.ts
new file mode 100644
index 0000000..cf7b45a
--- /dev/null
+++ b/src/client/models/webhookDeliveryResponse.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WebhookDeliveryResponse {
+  created_at: string;
+  /** @nullable */
+  delivered_at?: string | null;
+  /** @nullable */
+  error?: string | null;
+  event: string;
+  id: string;
+  /** @nullable */
+  response_status?: number | null;
+  webhook: string;
+}
diff --git a/src/client/models/webhookResponse.ts b/src/client/models/webhookResponse.ts
new file mode 100644
index 0000000..40c38ce
--- /dev/null
+++ b/src/client/models/webhookResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WebhookResponse {
+  active: boolean;
+  created_at: string;
+  created_by: string;
+  events: string[];
+  id: string;
+  repo: string;
+  updated_at: string;
+  url: string;
+}
diff --git a/src/client/models/workspaceGroupResponse.ts b/src/client/models/workspaceGroupResponse.ts
new file mode 100644
index 0000000..3c459a8
--- /dev/null
+++ b/src/client/models/workspaceGroupResponse.ts
@@ -0,0 +1,15 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WorkspaceGroupResponse {
+  /** @nullable */
+  avatar_url?: string | null;
+  created_at: string;
+  is_deleted: boolean;
+  name: string;
+}
diff --git a/src/client/models/workspaceJoinApplyResponse.ts b/src/client/models/workspaceJoinApplyResponse.ts
new file mode 100644
index 0000000..e4b5443
--- /dev/null
+++ b/src/client/models/workspaceJoinApplyResponse.ts
@@ -0,0 +1,24 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WorkspaceJoinApplyResponse {
+  /** @nullable */
+  answer?: string | null;
+  /** @nullable */
+  avatar_url?: string | null;
+  created_at: string;
+  /** @nullable */
+  message?: string | null;
+  /** @nullable */
+  question?: string | null;
+  status: string;
+  updated_at: string;
+  username: string;
+  workspace_avatar_url: string;
+  workspace_name: string;
+}
diff --git a/src/client/models/workspaceJoinApprovalResponse.ts b/src/client/models/workspaceJoinApprovalResponse.ts
new file mode 100644
index 0000000..47d76cd
--- /dev/null
+++ b/src/client/models/workspaceJoinApprovalResponse.ts
@@ -0,0 +1,22 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WorkspaceJoinApprovalResponse {
+  approved: boolean;
+  /** @nullable */
+  approver_avatar_url?: string | null;
+  approver_username: string;
+  /** @nullable */
+  avatar_url?: string | null;
+  created_at: string;
+  /** @nullable */
+  reason?: string | null;
+  username: string;
+  workspace_avatar_url: string;
+  workspace_name: string;
+}
diff --git a/src/client/models/workspaceJoinStrategyResponse.ts b/src/client/models/workspaceJoinStrategyResponse.ts
new file mode 100644
index 0000000..4713654
--- /dev/null
+++ b/src/client/models/workspaceJoinStrategyResponse.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WorkspaceJoinStrategyResponse {
+  created_at: string;
+  enabled: boolean;
+  has_answer: boolean;
+  /** @nullable */
+  question?: string | null;
+  require_approval: boolean;
+  require_question: boolean;
+  updated_at: string;
+  workspace_avatar_url: string;
+  workspace_name: string;
+}
diff --git a/src/client/models/workspaceListJoinAppliesParams.ts b/src/client/models/workspaceListJoinAppliesParams.ts
new file mode 100644
index 0000000..b537505
--- /dev/null
+++ b/src/client/models/workspaceListJoinAppliesParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type WorkspaceListJoinAppliesParams = {
+/**
+ * @nullable
+ */
+status?: string | null;
+};
diff --git a/src/client/models/workspaceListMembersParams.ts b/src/client/models/workspaceListMembersParams.ts
new file mode 100644
index 0000000..24a4ac9
--- /dev/null
+++ b/src/client/models/workspaceListMembersParams.ts
@@ -0,0 +1,20 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export type WorkspaceListMembersParams = {
+/**
+ * @minimum 0
+ * @nullable
+ */
+offset?: number | null;
+/**
+ * @minimum 0
+ * @nullable
+ */
+limit?: number | null;
+};
diff --git a/src/client/models/workspaceMemberResponse.ts b/src/client/models/workspaceMemberResponse.ts
new file mode 100644
index 0000000..410e1dd
--- /dev/null
+++ b/src/client/models/workspaceMemberResponse.ts
@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WorkspaceMemberResponse {
+  admin: boolean;
+  /** @nullable */
+  avatar_url?: string | null;
+  /** @nullable */
+  display_name?: string | null;
+  join_at: string;
+  owner: boolean;
+  username: string;
+}
diff --git a/src/client/models/workspaceResponse.ts b/src/client/models/workspaceResponse.ts
new file mode 100644
index 0000000..212481c
--- /dev/null
+++ b/src/client/models/workspaceResponse.ts
@@ -0,0 +1,16 @@
+/**
+ * Generated by orval v8.12.3 🍺
+ * Do not edit manually.
+ * GitDataAI API
+ * GitDataAI platform REST API
+ * OpenAPI spec version: 1.0.0
+ */
+
+export interface WorkspaceResponse {
+  admin: boolean;
+  avatar_url: string;
+  created_at: string;
+  description: string;
+  name: string;
+  owner: boolean;
+}
diff --git a/src/components/CodePreviewPanel.tsx b/src/components/CodePreviewPanel.tsx
new file mode 100644
index 0000000..30297d6
--- /dev/null
+++ b/src/components/CodePreviewPanel.tsx
@@ -0,0 +1,136 @@
+import { createContext, useContext, useState, useCallback, type ReactNode } from "react";
+import { PanelRightClose, Copy, Check } from "lucide-react";
+
+export interface CodePreviewPayload {
+  id: string;
+  code: string;
+  language: string;
+  title?: string;
+  subtitle?: string;
+  kind?: "code" | "subagent";
+  status?: "pending" | "ok" | "error" | "stopped";
+  onStop?: () => void;
+}
+
+interface CodePreviewContextValue {
+  activeCode: CodePreviewPayload | null;
+  openCodePreview: (payload: CodePreviewPayload) => void;
+  closeCodePreview: () => void;
+  updateCodePreview: (updates: Partial<CodePreviewPayload>) => void;
+}
+
+const CodePreviewContext = createContext<CodePreviewContextValue | null>(null);
+
+export function CodePreviewProvider({ children }: { children: ReactNode }) {
+  const [activeCode, setActiveCode] = useState<CodePreviewPayload | null>(null);
+
+  const openCodePreview = useCallback((payload: CodePreviewPayload) => {
+    setActiveCode(payload);
+  }, []);
+
+  const closeCodePreview = useCallback(() => {
+    setActiveCode(null);
+  }, []);
+
+  const updateCodePreview = useCallback((updates: Partial<CodePreviewPayload>) => {
+    setActiveCode((prev) => (prev ? { ...prev, ...updates } : null));
+  }, []);
+
+  return (
+    <CodePreviewContext.Provider
+      value={{ activeCode, openCodePreview, closeCodePreview, updateCodePreview }}
+    >
+      {children}
+    </CodePreviewContext.Provider>
+  );
+}
+
+export function useCodePreview() {
+  const ctx = useContext(CodePreviewContext);
+  return ctx;
+}
+
+export function CodePreviewPanel() {
+  const { activeCode, closeCodePreview, updateCodePreview } = useCodePreview() || {};
+  const [copied, setCopied] = useState(false);
+
+  if (!activeCode) return null;
+
+  const lines = activeCode.code.replace(/\n$/, "").split("\n");
+  const isSubAgent = activeCode.kind === "subagent";
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(activeCode.code).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  };
+
+  const handleStop = () => {
+    activeCode.onStop?.();
+    updateCodePreview?.({ status: "stopped" });
+  };
+
+  return (
+    <aside
+      className="flex h-full w-[min(50vw,600px)] shrink-0 flex-col border-l border-border bg-background transition-all duration-300"
+      style={{
+        animation: "slideInRight 0.3s ease-out",
+      }}
+    >
+      {/* Header */}
+      <div className="flex h-12 shrink-0 items-center justify-between border-b border-border px-4">
+        <div className="min-w-0 flex-1">
+          <div className="truncate text-sm font-medium text-foreground">
+            {activeCode.title || activeCode.language || "Code"}
+          </div>
+          <div className="truncate text-xs text-muted-foreground">
+            {activeCode.subtitle || `${lines.length} lines`}
+          </div>
+        </div>
+        <div className="flex items-center gap-1">
+          {isSubAgent && activeCode.status === "pending" && (
+            <button
+              onClick={handleStop}
+              className="flex items-center gap-1 rounded px-2 py-1 text-xs text-destructive transition-colors hover:bg-destructive/10"
+            >
+              Stop
+            </button>
+          )}
+          <button
+            onClick={handleCopy}
+            className="flex items-center gap-1 rounded px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+          >
+            {copied ? <Check className="size-3" /> : <Copy className="size-3" />}
+            {copied ? "Copied" : "Copy"}
+          </button>
+          <button
+            onClick={closeCodePreview}
+            className="rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+          >
+            <PanelRightClose className="size-4" />
+          </button>
+        </div>
+      </div>
+
+      {/* Code content */}
+      <div className="min-h-0 flex-1 overflow-auto">
+        <div className="grid min-w-max grid-cols-[auto_1fr] text-[13px] leading-[1.6]">
+          {/* Line numbers */}
+          <div
+            className="select-none border-r border-border px-3 py-4 text-right font-mono text-xs tabular-nums text-muted-foreground"
+            aria-hidden="true"
+          >
+            {lines.map((_, index) => (
+              <div key={index}>{index + 1}</div>
+            ))}
+          </div>
+          {/* Code */}
+          <pre className="m-0 min-h-full overflow-x-auto px-4 py-4 font-mono text-sm text-foreground">
+            <code>{activeCode.code || (activeCode.status === "pending" ? "Waiting for output..." : "")}</code>
+          </pre>
+        </div>
+      </div>
+    </aside>
+  );
+}
diff --git a/src/components/CommandPalette.tsx b/src/components/CommandPalette.tsx
new file mode 100644
index 0000000..2686fad
--- /dev/null
+++ b/src/components/CommandPalette.tsx
@@ -0,0 +1,384 @@
+import { useState, useEffect, useMemo, useCallback, useRef } from "react";
+import { useNavigate } from "react-router";
+import { Command } from "cmdk";
+import {
+  Search,
+  Building2,
+  FolderGit2,
+  Hash,
+  CircleDot,
+  Loader2,
+  AlertCircle,
+  CornerDownLeft,
+  ArrowUpDown,
+  X,
+} from "lucide-react";
+import { api } from "@/client";
+
+// ---- Types ----
+
+type HitType = "workspace" | "repo" | "room" | "issue";
+
+interface SearchHit {
+  id: string;
+  type: HitType;
+  label: string;
+  subtitle: string;
+  url: string;
+  meta?: string;
+  metaTone?: "success" | "muted" | "warning";
+}
+
+interface SearchGroup<T> {
+  items: T[];
+  total: number;
+  has_more: boolean;
+}
+
+interface SearchResponse {
+  workspaces: SearchGroup<{ name: string; description?: string | null }>;
+  repos: SearchGroup<{ name: string; workspace: string; description?: string | null }>;
+  rooms: SearchGroup<{ id: string; name: string; workspace: string }>;
+  issues: SearchGroup<{ number: number; title: string; state: string; workspace: string }>;
+}
+
+const TYPE_ICONS: Record<HitType, typeof Building2> = {
+  workspace: Building2,
+  repo: FolderGit2,
+  room: Hash,
+  issue: CircleDot,
+};
+
+const TYPE_LABELS: Record<HitType, string> = {
+  workspace: "Workspaces",
+  repo: "Repositories",
+  room: "Channels",
+  issue: "Issues",
+};
+
+const PLACEHOLDERS = [
+  "Search workspaces, repos, channels...",
+  "Find an issue...",
+  "Jump to a channel...",
+  "Open a repository...",
+];
+
+// ---- Helpers ----
+
+function buildHits(data: SearchResponse): SearchHit[] {
+  const results: SearchHit[] = [];
+
+  for (const ws of data.workspaces.items) {
+    results.push({
+      id: `ws-${ws.name}`,
+      type: "workspace",
+      label: ws.name,
+      subtitle: ws.description || "Workspace",
+      url: `/${ws.name}`,
+    });
+  }
+
+  for (const repo of data.repos.items) {
+    results.push({
+      id: `repo-${repo.workspace}-${repo.name}`,
+      type: "repo",
+      label: `${repo.workspace}/${repo.name}`,
+      subtitle: repo.description || "Repository",
+      url: `/${repo.workspace}/repo/${repo.name}`,
+    });
+  }
+
+  for (const room of data.rooms.items) {
+    results.push({
+      id: `room-${room.id}`,
+      type: "room",
+      label: `#${room.name}`,
+      subtitle: "Channel",
+      url: `/${room.workspace}/channel/${room.id}`,
+    });
+  }
+
+  for (const issue of data.issues.items) {
+    results.push({
+      id: `issue-${issue.workspace}-${issue.number}`,
+      type: "issue",
+      label: `#${issue.number} ${issue.title}`,
+      subtitle: issue.workspace,
+      meta: issue.state,
+      metaTone: issue.state === "open" ? "success" : "muted",
+      url: `/${issue.workspace}/issues/${issue.number}`,
+    });
+  }
+
+  return results;
+}
+
+// ---- Component ----
+
+export function CommandPalette() {
+  const [open, setOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [items, setItems] = useState<SearchHit[]>([]);
+  const [search, setSearch] = useState("");
+  const [placeholderIndex, setPlaceholderIndex] = useState(0);
+  const navigate = useNavigate();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Rotating placeholder
+  useEffect(() => {
+    if (!open) return;
+    const interval = setInterval(() => {
+      setPlaceholderIndex((i) => (i + 1) % PLACEHOLDERS.length);
+    }, 3000);
+    return () => clearInterval(interval);
+  }, [open]);
+
+  // Fetch data
+  const fetchData = useCallback(async (q: string) => {
+    setLoading(true);
+    setError(null);
+    try {
+      const { data } = await api.get<SearchResponse>("/api/v1/search", {
+        params: q.trim() ? { q: q.trim() } : {},
+      });
+      setItems(buildHits(data));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Search failed");
+      setItems([]);
+    }
+    setLoading(false);
+  }, []);
+
+  // Pre-fetch on open, debounced re-fetch on type
+  useEffect(() => {
+    if (!open) return;
+    const timer = setTimeout(() => fetchData(search), search ? 150 : 0);
+    return () => clearTimeout(timer);
+  }, [open, search, fetchData]);
+
+  // Reset on close
+  const handleOpenChange = useCallback((o: boolean) => {
+    setOpen(o);
+    if (!o) {
+      setSearch("");
+      setError(null);
+    }
+  }, []);
+
+  // Group by type
+  const grouped = useMemo(() => {
+    const g: Record<string, SearchHit[]> = {};
+    for (const it of items) {
+      const key = TYPE_LABELS[it.type];
+      (g[key] ??= []).push(it);
+    }
+    return g;
+  }, [items]);
+
+  const totalHits = items.length;
+
+  // ⌘K global shortcut
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((v) => !v);
+      }
+    };
+    document.addEventListener("keydown", down);
+    return () => document.removeEventListener("keydown", down);
+  }, []);
+
+  const handleSelect = useCallback(
+    (url: string) => {
+      setOpen(false);
+      navigate(url);
+    },
+    [navigate],
+  );
+
+  return (
+    <>
+      {/* Trigger button */}
+      <button
+        aria-label="Open command palette (⌘K)"
+        className="inline-flex items-center gap-2 rounded-lg border border-border/60 bg-muted/40 px-3 py-1.5 text-xs text-muted-foreground transition-all duration-150 hover:border-border hover:bg-muted hover:text-foreground hover:shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        onClick={() => setOpen(true)}
+        type="button"
+      >
+        <Search className="size-3.5" />
+        <span className="hidden sm:inline">Quick jump...</span>
+        <kbd className="ml-1 hidden rounded border border-border bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground sm:inline">
+          ⌘K
+        </kbd>
+      </button>
+
+      {/* Modal dialog */}
+      <Command.Dialog
+        label="Command Palette"
+        onOpenChange={handleOpenChange}
+        open={open}
+      >
+        {/* Search input */}
+        <div className="flex items-center gap-3 border-b border-border px-4 py-0.5">
+          <Search className="size-4 shrink-0 text-muted-foreground/60" />
+          <Command.Input
+            autoFocus
+            className="flex-1 bg-transparent py-3 text-[15px] outline-none placeholder:text-muted-foreground/40"
+            onValueChange={setSearch}
+            placeholder={PLACEHOLDERS[placeholderIndex]}
+            ref={inputRef}
+            value={search}
+          />
+          <div className="flex items-center gap-1.5">
+            {loading && (
+              <Loader2 className="size-4 animate-spin text-muted-foreground/50" />
+            )}
+            {error && (
+              <AlertCircle className="size-4 text-destructive/70" />
+            )}
+          </div>
+        </div>
+
+        {/* Results list */}
+        <Command.List className="max-h-[420px] overflow-y-auto overscroll-contain p-1">
+          {/* Error state */}
+          {error && (
+            <div className="flex flex-col items-center gap-2 px-4 py-10">
+              <div className="grid size-10 place-items-center rounded-full bg-destructive/10">
+                <AlertCircle className="size-5 text-destructive/70" />
+              </div>
+              <p className="text-sm text-muted-foreground">{error}</p>
+              <button
+                className="mt-1 rounded-md px-3 py-1 text-xs text-primary transition-colors hover:bg-primary/10"
+                onClick={() => fetchData(search)}
+                type="button"
+              >
+                Retry
+              </button>
+            </div>
+          )}
+
+          {/* Empty state */}
+          {!error && !loading && totalHits === 0 && (
+            <div className="flex flex-col items-center gap-2 px-4 py-10">
+              <div className="grid size-10 place-items-center rounded-full bg-muted/50">
+                <Search className="size-5 text-muted-foreground/30" />
+              </div>
+              <p className="text-sm text-muted-foreground">
+                {search.trim()
+                  ? `No results for "${search.trim()}"`
+                  : "Type to search across all workspaces"}
+              </p>
+            </div>
+          )}
+
+          {/* Loading skeleton */}
+          {loading && totalHits === 0 && !error && (
+            <div className="space-y-3 px-4 py-4">
+              {Array.from({ length: 4 }).map((_, i) => (
+                <div className="flex items-center gap-3" key={i}>
+                  <div className="size-4 animate-pulse rounded bg-muted/50" />
+                  <div className="flex-1 space-y-1.5">
+                    <div className="h-4 w-3/5 animate-pulse rounded bg-muted/50" />
+                    <div className="h-3 w-2/5 animate-pulse rounded bg-muted/40" />
+                  </div>
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Grouped results */}
+          {Object.entries(grouped).map(([groupName, groupItems]) => (
+            <Command.Group
+              heading={
+                <span className="flex items-center gap-2">
+                  {groupName}
+                  <span className="rounded bg-muted/50 px-1.5 py-0.5 text-[10px] tabular-nums text-muted-foreground/60">
+                    {groupItems.length}
+                  </span>
+                </span>
+              }
+              key={groupName}
+            >
+              {groupItems.map((item) => {
+                const Icon = TYPE_ICONS[item.type];
+                return (
+                  <Command.Item
+                    aria-label={`${item.type}: ${item.label}`}
+                    className="group mx-0 flex cursor-pointer items-center gap-3 rounded-lg px-3 py-2.5 text-sm transition-colors aria-selected:bg-accent"
+                    key={item.id}
+                    onSelect={() => handleSelect(item.url)}
+                    value={item.id}
+                  >
+                    <span
+                      className={`grid size-8 shrink-0 place-items-center rounded-lg ${
+                        item.type === "issue"
+                          ? "bg-amber-500/10 text-amber-600 dark:text-amber-400"
+                          : item.type === "repo"
+                            ? "bg-blue-500/10 text-blue-600 dark:text-blue-400"
+                            : item.type === "room"
+                              ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+                              : "bg-primary/10 text-primary"
+                      }`}
+                    >
+                      <Icon className="size-4" />
+                    </span>
+                    <div className="min-w-0 flex-1">
+                      <div className="truncate text-[14px] font-medium text-foreground">
+                        {item.label}
+                      </div>
+                      <div className="flex items-center gap-1.5">
+                        <span className="truncate text-xs text-muted-foreground/60">
+                          {item.subtitle}
+                        </span>
+                        {item.meta && (
+                          <span
+                            className={`shrink-0 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${
+                              item.metaTone === "success"
+                                ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+                                : "bg-muted/60 text-muted-foreground/60"
+                            }`}
+                          >
+                            {item.meta}
+                          </span>
+                        )}
+                      </div>
+                    </div>
+                    <kbd className="hidden shrink-0 rounded border border-border bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground/40 group-aria-selected:text-foreground/50">
+                      ↵
+                    </kbd>
+                  </Command.Item>
+                );
+              })}
+            </Command.Group>
+          ))}
+        </Command.List>
+
+        {/* Footer */}
+        <div className="flex items-center justify-between border-t border-border px-4 py-2 text-[11px] text-muted-foreground/40">
+          <div className="flex items-center gap-3">
+            <span className="inline-flex items-center gap-1">
+              <ArrowUpDown className="size-3" />
+              Navigate
+            </span>
+            <span className="inline-flex items-center gap-1">
+              <CornerDownLeft className="size-3" />
+              Open
+            </span>
+            <span className="inline-flex items-center gap-1">
+              <X className="size-3" />
+              Close
+            </span>
+          </div>
+          {totalHits > 0 && (
+            <span className="tabular-nums">
+              {totalHits} result{totalHits !== 1 ? "s" : ""}
+            </span>
+          )}
+        </div>
+      </Command.Dialog>
+    </>
+  );
+}
diff --git a/src/components/MarkdownRenderer.tsx b/src/components/MarkdownRenderer.tsx
new file mode 100644
index 0000000..be42e9a
--- /dev/null
+++ b/src/components/MarkdownRenderer.tsx
@@ -0,0 +1,233 @@
+import { memo, useMemo, useState, useCallback } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { Check, Copy, Code2, PanelRightOpen } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+interface MarkdownRendererProps {
+  content: string;
+  className?: string;
+  /** Called when user clicks to open a code block in a side panel. */
+  onOpenCodePanel?: (payload: {
+    code: string;
+    language: string;
+    lineCount: number;
+    title?: string;
+  }) => void;
+}
+
+/** Extract plain text from react-markdown children (string or array). */
+function extractText(children: React.ReactNode): string {
+  if (typeof children === "string") return children;
+  if (Array.isArray(children)) {
+    return children.map((c) => (typeof c === "string" ? c : "")).join("");
+  }
+  return "";
+}
+
+/**
+ * Code block wrapped in Artifact-style container.
+ */
+const ArtifactCodeBlock = memo(function ArtifactCodeBlock({
+  language,
+  children,
+  onOpen,
+}: {
+  language: string;
+  children: string;
+  onOpen?: () => void;
+}) {
+  const [copied, setCopied] = useState(false);
+  const lines = useMemo(
+    () => children.replace(/\n$/, "").split("\n"),
+    [children],
+  );
+
+  const handleCopy = useCallback(() => {
+    navigator.clipboard
+      .writeText(children)
+      .then(() => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      })
+      .catch(() => {});
+  }, [children]);
+
+  return (
+    <div
+      className={cn(
+        "not-prose my-4 overflow-hidden rounded-xl border bg-card shadow-sm transition-colors",
+        onOpen
+          ? "cursor-pointer border-border/60 hover:border-primary/40"
+          : "border-border",
+      )}
+      onClick={onOpen}
+      role={onOpen ? "button" : undefined}
+      tabIndex={onOpen ? 0 : undefined}
+      onKeyDown={
+        onOpen
+          ? (e: React.KeyboardEvent) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onOpen();
+              }
+            }
+          : undefined
+      }
+      aria-label={onOpen ? `Open ${language || "code"} in side panel` : undefined}
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between border-b border-border/60 bg-muted/40 px-4 py-2.5">
+        <div className="flex items-center gap-2">
+          <span className="grid size-6 place-items-center rounded-md bg-muted">
+            <Code2 className="size-3.5 text-muted-foreground" />
+          </span>
+          <span className="text-xs font-medium text-foreground">
+            {language || "code"}
+          </span>
+          <span className="hidden sm:inline text-[11px] text-muted-foreground/50">
+            {lines.length} line{lines.length !== 1 ? "s" : ""}
+          </span>
+        </div>
+        <div className="flex items-center gap-1">
+          {onOpen && (
+            <span className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs text-muted-foreground">
+              <PanelRightOpen className="size-3" />
+              Open in panel
+            </span>
+          )}
+          {!onOpen && (
+            <button
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+                copied
+                  ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+                  : "text-muted-foreground hover:bg-muted hover:text-foreground",
+              )}
+              onClick={(e) => {
+                e.stopPropagation();
+                handleCopy();
+              }}
+              type="button"
+            >
+              {copied ? (
+                <>
+                  <Check className="size-3" />
+                  Copied
+                </>
+              ) : (
+                <>
+                  <Copy className="size-3" />
+                  Copy
+                </>
+              )}
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Content with line numbers — only when no side panel (inline mode) */}
+      {!onOpen && (
+        <div className="grid min-w-max grid-cols-[auto_1fr]">
+          <div
+            aria-hidden="true"
+            className="select-none border-r border-border/40 bg-muted/20 px-3 py-3 text-right font-mono text-xs tabular-nums leading-[1.65] text-muted-foreground/40"
+          >
+            {lines.map((_, i) => (
+              <div key={i}>{i + 1}</div>
+            ))}
+          </div>
+          <pre className="m-0 overflow-x-auto px-4 py-3 font-mono text-sm leading-[1.65] text-foreground/90">
+            <code className={cn(language && `language-${language}`)}>
+              {children.replace(/\n$/, "")}
+            </code>
+          </pre>
+        </div>
+      )}
+
+      {/* Compact summary when panel mode */}
+      {onOpen && (
+        <div className="px-4 py-2.5">
+          <p className="text-xs text-muted-foreground/60">
+            {lines[0]?.slice(0, 80)}{(lines[0]?.length ?? 0) > 80 ? "…" : ""}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+});
+
+export const MarkdownRenderer = memo(function MarkdownRenderer({
+  content,
+  className = "",
+  onOpenCodePanel,
+}: MarkdownRendererProps) {
+  const components = useMemo(
+    () => ({
+      code({
+        className: codeClassName,
+        children,
+        ...props
+      }: {
+        className?: string;
+        children: React.ReactNode;
+        node?: unknown;
+      }) {
+        const match = /language-(\w+)/.exec(codeClassName || "");
+        const codeContent = extractText(children).replace(/\n$/, "");
+        const isInline = !match && !codeContent.includes("\n");
+
+        if (isInline) {
+          return (
+            <code
+              className="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.9em] text-foreground/90"
+              {...props}
+            >
+              {extractText(children)}
+            </code>
+          );
+        }
+
+        return (
+          <ArtifactCodeBlock
+            language={match?.[1] || ""}
+            onOpen={
+              onOpenCodePanel
+                ? () =>
+                    onOpenCodePanel({
+                      code: codeContent,
+                      language: match?.[1] || "text",
+                      lineCount: codeContent.split("\n").length,
+                    })
+                : undefined
+            }
+          >
+            {codeContent}
+          </ArtifactCodeBlock>
+        );
+      },
+      pre({ children }: { children: React.ReactNode }) {
+        return <>{children}</>;
+      },
+    }),
+    [onOpenCodePanel],
+  );
+
+  return (
+    <div
+      className={cn(
+        "prose prose-sm dark:prose-invert max-w-none",
+        className,
+      )}
+    >
+      <ReactMarkdown
+        components={components as any}
+        remarkPlugins={[remarkGfm]}
+      >
+        {content}
+      </ReactMarkdown>
+    </div>
+  );
+});
+
+export default MarkdownRenderer;
diff --git a/src/components/Reasoning.tsx b/src/components/Reasoning.tsx
new file mode 100644
index 0000000..1a70627
--- /dev/null
+++ b/src/components/Reasoning.tsx
@@ -0,0 +1,57 @@
+import { useState, type ReactNode } from "react";
+import { Brain, ChevronDown } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+interface ReasoningProps {
+  children: ReactNode;
+  defaultOpen?: boolean;
+  summary?: string;
+}
+
+export function Reasoning({ children, defaultOpen = false, summary }: ReasoningProps) {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+
+  return (
+    <div className="my-2 overflow-hidden rounded-lg border border-border bg-card">
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className="flex w-full items-center gap-2 px-3 py-2 text-left text-sm transition-colors hover:bg-muted/50"
+      >
+        <Brain className="size-4 shrink-0 text-violet-500" />
+        <span className="flex-1 font-medium text-foreground">
+          {summary || "Thinking process"}
+        </span>
+        <ChevronDown
+          className={cn(
+            "size-4 shrink-0 text-muted-foreground transition-transform",
+            isOpen && "rotate-180"
+          )}
+        />
+      </button>
+      {isOpen && (
+        <div className="border-t border-border px-3 py-2 text-sm text-muted-foreground">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface ThinkingBlockProps {
+  content: string;
+  isStreaming?: boolean;
+}
+
+export function ThinkingBlock({ content, isStreaming }: ThinkingBlockProps) {
+  return (
+    <Reasoning summary="Thinking...">
+      <div className="whitespace-pre-wrap break-words text-xs leading-relaxed">
+        {content}
+        {isStreaming && (
+          <span className="ml-0.5 inline-block size-1.5 animate-pulse rounded-full bg-violet-500 align-middle" />
+        )}
+      </div>
+    </Reasoning>
+  );
+}
diff --git a/src/components/ai-elements/artifact.tsx b/src/components/ai-elements/artifact.tsx
new file mode 100644
index 0000000..0597d4a
--- /dev/null
+++ b/src/components/ai-elements/artifact.tsx
@@ -0,0 +1,148 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import type { LucideIcon } from "lucide-react";
+import { XIcon } from "lucide-react";
+import type { ComponentProps, HTMLAttributes } from "react";
+
+export type ArtifactProps = HTMLAttributes<HTMLDivElement>;
+
+export const Artifact = ({ className, ...props }: ArtifactProps) => (
+  <div
+    className={cn(
+      "flex flex-col overflow-hidden rounded-lg border bg-background shadow-sm",
+      className
+    )}
+    {...props}
+  />
+);
+
+export type ArtifactHeaderProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactHeader = ({
+  className,
+  ...props
+}: ArtifactHeaderProps) => (
+  <div
+    className={cn(
+      "flex items-center justify-between border-b bg-muted/50 px-4 py-3",
+      className
+    )}
+    {...props}
+  />
+);
+
+export type ArtifactCloseProps = ComponentProps<typeof Button>;
+
+export const ArtifactClose = ({
+  className,
+  children,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: ArtifactCloseProps) => (
+  <Button
+    className={cn(
+      "size-8 p-0 text-muted-foreground hover:text-foreground",
+      className
+    )}
+    size={size}
+    type="button"
+    variant={variant}
+    {...props}
+  >
+    {children ?? <XIcon className="size-4" />}
+    <span className="sr-only">Close</span>
+  </Button>
+);
+
+export type ArtifactTitleProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const ArtifactTitle = ({ className, ...props }: ArtifactTitleProps) => (
+  <p
+    className={cn("font-medium text-foreground text-sm", className)}
+    {...props}
+  />
+);
+
+export type ArtifactDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const ArtifactDescription = ({
+  className,
+  ...props
+}: ArtifactDescriptionProps) => (
+  <p className={cn("text-muted-foreground text-sm", className)} {...props} />
+);
+
+export type ArtifactActionsProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactActions = ({
+  className,
+  ...props
+}: ArtifactActionsProps) => (
+  <div className={cn("flex items-center gap-1", className)} {...props} />
+);
+
+export type ArtifactActionProps = ComponentProps<typeof Button> & {
+  tooltip?: string;
+  label?: string;
+  icon?: LucideIcon;
+};
+
+export const ArtifactAction = ({
+  tooltip,
+  label,
+  icon: Icon,
+  children,
+  className,
+  size = "sm",
+  variant = "ghost",
+  ...props
+}: ArtifactActionProps) => {
+  const button = (
+    <Button
+      className={cn(
+        "size-8 p-0 text-muted-foreground hover:text-foreground",
+        className
+      )}
+      size={size}
+      type="button"
+      variant={variant}
+      {...props}
+    >
+      {Icon ? <Icon className="size-4" /> : children}
+      <span className="sr-only">{label || tooltip}</span>
+    </Button>
+  );
+
+  if (tooltip) {
+    return (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger>{button}</TooltipTrigger>
+          <TooltipContent>
+            <p>{tooltip}</p>
+          </TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
+  }
+
+  return button;
+};
+
+export type ArtifactContentProps = HTMLAttributes<HTMLDivElement>;
+
+export const ArtifactContent = ({
+  className,
+  ...props
+}: ArtifactContentProps) => (
+  <div className={cn("flex-1 overflow-auto p-4", className)} {...props} />
+);
diff --git a/src/components/ai-elements/code-block.tsx b/src/components/ai-elements/code-block.tsx
new file mode 100644
index 0000000..bc1441a
--- /dev/null
+++ b/src/components/ai-elements/code-block.tsx
@@ -0,0 +1,562 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import type { ComponentProps, CSSProperties, HTMLAttributes } from "react";
+import {
+  createContext,
+  memo,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type {
+  BundledLanguage,
+  BundledTheme,
+  HighlighterGeneric,
+  ThemedToken,
+} from "shiki";
+import { createHighlighter } from "shiki";
+
+// Shiki uses bitflags for font styles: 1=italic, 2=bold, 4=underline
+// oxlint-disable-next-line eslint(no-bitwise)
+const isItalic = (fontStyle: number | undefined) => fontStyle && fontStyle & 1;
+// oxlint-disable-next-line eslint(no-bitwise)
+const isBold = (fontStyle: number | undefined) => fontStyle && fontStyle & 2;
+const isUnderline = (fontStyle: number | undefined) =>
+  // oxlint-disable-next-line eslint(no-bitwise)
+  fontStyle && fontStyle & 4;
+
+// Transform tokens to include pre-computed keys to avoid noArrayIndexKey lint
+interface KeyedToken {
+  token: ThemedToken;
+  key: string;
+}
+interface KeyedLine {
+  tokens: KeyedToken[];
+  key: string;
+}
+
+const addKeysToTokens = (lines: ThemedToken[][]): KeyedLine[] =>
+  lines.map((line, lineIdx) => ({
+    key: `line-${lineIdx}`,
+    tokens: line.map((token, tokenIdx) => ({
+      key: `line-${lineIdx}-${tokenIdx}`,
+      token,
+    })),
+  }));
+
+// Token rendering component
+const TokenSpan = ({ token }: { token: ThemedToken }) => (
+  <span
+    className="dark:!bg-[var(--shiki-dark-bg)] dark:!text-[var(--shiki-dark)]"
+    style={
+      {
+        backgroundColor: token.bgColor,
+        color: token.color,
+        fontStyle: isItalic(token.fontStyle) ? "italic" : undefined,
+        fontWeight: isBold(token.fontStyle) ? "bold" : undefined,
+        textDecoration: isUnderline(token.fontStyle) ? "underline" : undefined,
+        ...token.htmlStyle,
+      } as CSSProperties
+    }
+  >
+    {token.content}
+  </span>
+);
+
+// Line number styles using CSS counters
+const LINE_NUMBER_CLASSES = cn(
+  "block",
+  "before:content-[counter(line)]",
+  "before:inline-block",
+  "before:[counter-increment:line]",
+  "before:w-8",
+  "before:mr-4",
+  "before:text-right",
+  "before:text-muted-foreground/50",
+  "before:font-mono",
+  "before:select-none"
+);
+
+// Line rendering component
+const LineSpan = ({
+  keyedLine,
+  showLineNumbers,
+}: {
+  keyedLine: KeyedLine;
+  showLineNumbers: boolean;
+}) => (
+  <span className={showLineNumbers ? LINE_NUMBER_CLASSES : "block"}>
+    {keyedLine.tokens.length === 0
+      ? "\n"
+      : keyedLine.tokens.map(({ token, key }) => (
+          <TokenSpan key={key} token={token} />
+        ))}
+  </span>
+);
+
+// Types
+type CodeBlockProps = HTMLAttributes<HTMLDivElement> & {
+  code: string;
+  language: BundledLanguage;
+  showLineNumbers?: boolean;
+};
+
+interface TokenizedCode {
+  tokens: ThemedToken[][];
+  fg: string;
+  bg: string;
+}
+
+interface CodeBlockContextType {
+  code: string;
+}
+
+// Context
+const CodeBlockContext = createContext<CodeBlockContextType>({
+  code: "",
+});
+
+// Highlighter cache (singleton per language)
+const highlighterCache = new Map<
+  string,
+  Promise<HighlighterGeneric<BundledLanguage, BundledTheme>>
+>();
+
+// Token cache
+const tokensCache = new Map<string, TokenizedCode>();
+
+// Subscribers for async token updates
+const subscribers = new Map<string, Set<(result: TokenizedCode) => void>>();
+
+const getTokensCacheKey = (code: string, language: BundledLanguage) => {
+  const start = code.slice(0, 100);
+  const end = code.length > 100 ? code.slice(-100) : "";
+  return `${language}:${code.length}:${start}:${end}`;
+};
+
+const getHighlighter = (
+  language: BundledLanguage
+): Promise<HighlighterGeneric<BundledLanguage, BundledTheme>> => {
+  const cached = highlighterCache.get(language);
+  if (cached) {
+    return cached;
+  }
+
+  const highlighterPromise = createHighlighter({
+    langs: [language],
+    themes: ["github-light", "github-dark"],
+  });
+
+  highlighterCache.set(language, highlighterPromise);
+  return highlighterPromise;
+};
+
+// Create raw tokens for immediate display while highlighting loads
+const createRawTokens = (code: string): TokenizedCode => ({
+  bg: "transparent",
+  fg: "inherit",
+  tokens: code.split("\n").map((line) =>
+    line === ""
+      ? []
+      : [
+          {
+            color: "inherit",
+            content: line,
+          } as ThemedToken,
+        ]
+  ),
+});
+
+// Synchronous highlight with callback for async results
+export const highlightCode = (
+  code: string,
+  language: BundledLanguage,
+  // oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-callbacks)
+  callback?: (result: TokenizedCode) => void
+): TokenizedCode | null => {
+  const tokensCacheKey = getTokensCacheKey(code, language);
+
+  // Return cached result if available
+  const cached = tokensCache.get(tokensCacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  // Subscribe callback if provided
+  if (callback) {
+    if (!subscribers.has(tokensCacheKey)) {
+      subscribers.set(tokensCacheKey, new Set());
+    }
+    subscribers.get(tokensCacheKey)?.add(callback);
+  }
+
+  // Start highlighting in background - fire-and-forget async pattern
+  getHighlighter(language)
+    // oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-then)
+    .then((highlighter) => {
+      const availableLangs = highlighter.getLoadedLanguages();
+      const langToUse = availableLangs.includes(language) ? language : "text";
+
+      const result = highlighter.codeToTokens(code, {
+        lang: langToUse,
+        themes: {
+          dark: "github-dark",
+          light: "github-light",
+        },
+      });
+
+      const tokenized: TokenizedCode = {
+        bg: result.bg ?? "transparent",
+        fg: result.fg ?? "inherit",
+        tokens: result.tokens,
+      };
+
+      // Cache the result
+      tokensCache.set(tokensCacheKey, tokenized);
+
+      // Notify all subscribers
+      const subs = subscribers.get(tokensCacheKey);
+      if (subs) {
+        for (const sub of subs) {
+          sub(tokenized);
+        }
+        subscribers.delete(tokensCacheKey);
+      }
+    })
+    // oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-then), eslint-plugin-promise(prefer-await-to-callbacks)
+    .catch((error) => {
+      console.error("Failed to highlight code:", error);
+      subscribers.delete(tokensCacheKey);
+    });
+
+  return null;
+};
+
+const CodeBlockBody = memo(
+  ({
+    tokenized,
+    showLineNumbers,
+    className,
+  }: {
+    tokenized: TokenizedCode;
+    showLineNumbers: boolean;
+    className?: string;
+  }) => {
+    const preStyle = useMemo(
+      () => ({
+        backgroundColor: tokenized.bg,
+        color: tokenized.fg,
+      }),
+      [tokenized.bg, tokenized.fg]
+    );
+
+    const keyedLines = useMemo(
+      () => addKeysToTokens(tokenized.tokens),
+      [tokenized.tokens]
+    );
+
+    return (
+      <pre
+        className={cn(
+          "dark:!bg-[var(--shiki-dark-bg)] dark:!text-[var(--shiki-dark)] m-0 p-4 text-sm",
+          className
+        )}
+        style={preStyle}
+      >
+        <code
+          className={cn(
+            "font-mono text-sm",
+            showLineNumbers && "[counter-increment:line_0] [counter-reset:line]"
+          )}
+        >
+          {keyedLines.map((keyedLine) => (
+            <LineSpan
+              key={keyedLine.key}
+              keyedLine={keyedLine}
+              showLineNumbers={showLineNumbers}
+            />
+          ))}
+        </code>
+      </pre>
+    );
+  },
+  (prevProps, nextProps) =>
+    prevProps.tokenized === nextProps.tokenized &&
+    prevProps.showLineNumbers === nextProps.showLineNumbers &&
+    prevProps.className === nextProps.className
+);
+
+CodeBlockBody.displayName = "CodeBlockBody";
+
+export const CodeBlockContainer = ({
+  className,
+  language,
+  style,
+  ...props
+}: HTMLAttributes<HTMLDivElement> & { language: string }) => (
+  <div
+    className={cn(
+      "group relative w-full overflow-hidden rounded-md border bg-background text-foreground",
+      className
+    )}
+    data-language={language}
+    style={{
+      containIntrinsicSize: "auto 200px",
+      contentVisibility: "auto",
+      ...style,
+    }}
+    {...props}
+  />
+);
+
+export const CodeBlockHeader = ({
+  children,
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn(
+      "flex items-center justify-between border-b bg-muted/80 px-3 py-2 text-muted-foreground text-xs",
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export const CodeBlockTitle = ({
+  children,
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) => (
+  <div className={cn("flex items-center gap-2", className)} {...props}>
+    {children}
+  </div>
+);
+
+export const CodeBlockFilename = ({
+  children,
+  className,
+  ...props
+}: HTMLAttributes<HTMLSpanElement>) => (
+  <span className={cn("font-mono", className)} {...props}>
+    {children}
+  </span>
+);
+
+export const CodeBlockActions = ({
+  children,
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("-my-1 -mr-1 flex items-center gap-2", className)}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export const CodeBlockContent = ({
+  code,
+  language,
+  showLineNumbers = false,
+}: {
+  code: string;
+  language: BundledLanguage;
+  showLineNumbers?: boolean;
+}) => {
+  // Memoized raw tokens for immediate display
+  const rawTokens = useMemo(() => createRawTokens(code), [code]);
+
+  // Synchronous cache lookup — avoids setState in effect for cached results
+  const syncTokens = useMemo(
+    () => highlightCode(code, language) ?? rawTokens,
+    [code, language, rawTokens]
+  );
+
+  // Async highlighting result (populated after shiki loads)
+  const [asyncTokens, setAsyncTokens] = useState<TokenizedCode | null>(null);
+  const asyncKeyRef = useRef({ code, language });
+
+  // Invalidate stale async tokens synchronously during render
+  if (
+    asyncKeyRef.current.code !== code ||
+    asyncKeyRef.current.language !== language
+  ) {
+    asyncKeyRef.current = { code, language };
+    setAsyncTokens(null);
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+
+    highlightCode(code, language, (result) => {
+      if (!cancelled) {
+        setAsyncTokens(result);
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [code, language]);
+
+  const tokenized = asyncTokens ?? syncTokens;
+
+  return (
+    <div className="relative overflow-auto">
+      <CodeBlockBody showLineNumbers={showLineNumbers} tokenized={tokenized} />
+    </div>
+  );
+};
+
+export const CodeBlock = ({
+  code,
+  language,
+  showLineNumbers = false,
+  className,
+  children,
+  ...props
+}: CodeBlockProps) => {
+  const contextValue = useMemo(() => ({ code }), [code]);
+
+  return (
+    <CodeBlockContext.Provider value={contextValue}>
+      <CodeBlockContainer className={className} language={language} {...props}>
+        {children}
+        <CodeBlockContent
+          code={code}
+          language={language}
+          showLineNumbers={showLineNumbers}
+        />
+      </CodeBlockContainer>
+    </CodeBlockContext.Provider>
+  );
+};
+
+export type CodeBlockCopyButtonProps = ComponentProps<typeof Button> & {
+  onCopy?: () => void;
+  onError?: (error: Error) => void;
+  timeout?: number;
+};
+
+export const CodeBlockCopyButton = ({
+  onCopy,
+  onError,
+  timeout = 2000,
+  children,
+  className,
+  ...props
+}: CodeBlockCopyButtonProps) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const timeoutRef = useRef<number>(0);
+  const { code } = useContext(CodeBlockContext);
+
+  const copyToClipboard = useCallback(async () => {
+    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+      onError?.(new Error("Clipboard API not available"));
+      return;
+    }
+
+    try {
+      if (!isCopied) {
+        await navigator.clipboard.writeText(code);
+        setIsCopied(true);
+        onCopy?.();
+        timeoutRef.current = window.setTimeout(
+          () => setIsCopied(false),
+          timeout
+        );
+      }
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }, [code, onCopy, onError, timeout, isCopied]);
+
+  useEffect(
+    () => () => {
+      window.clearTimeout(timeoutRef.current);
+    },
+    []
+  );
+
+  const Icon = isCopied ? CheckIcon : CopyIcon;
+
+  return (
+    <Button
+      className={cn("shrink-0", className)}
+      onClick={copyToClipboard}
+      size="icon"
+      variant="ghost"
+      {...props}
+    >
+      {children ?? <Icon size={14} />}
+    </Button>
+  );
+};
+
+export type CodeBlockLanguageSelectorProps = ComponentProps<typeof Select>;
+
+export const CodeBlockLanguageSelector = (
+  props: CodeBlockLanguageSelectorProps
+) => <Select {...props} />;
+
+export type CodeBlockLanguageSelectorTriggerProps = ComponentProps<
+  typeof SelectTrigger
+>;
+
+export const CodeBlockLanguageSelectorTrigger = ({
+  className,
+  ...props
+}: CodeBlockLanguageSelectorTriggerProps) => (
+  <SelectTrigger
+    className={cn(
+      "h-7 border-none bg-transparent px-2 text-xs shadow-none",
+      className
+    )}
+    size="sm"
+    {...props}
+  />
+);
+
+export type CodeBlockLanguageSelectorValueProps = ComponentProps<
+  typeof SelectValue
+>;
+
+export const CodeBlockLanguageSelectorValue = (
+  props: CodeBlockLanguageSelectorValueProps
+) => <SelectValue {...props} />;
+
+export type CodeBlockLanguageSelectorContentProps = ComponentProps<
+  typeof SelectContent
+>;
+
+export const CodeBlockLanguageSelectorContent = ({
+  align = "end",
+  ...props
+}: CodeBlockLanguageSelectorContentProps) => (
+  <SelectContent align={align} {...props} />
+);
+
+export type CodeBlockLanguageSelectorItemProps = ComponentProps<
+  typeof SelectItem
+>;
+
+export const CodeBlockLanguageSelectorItem = (
+  props: CodeBlockLanguageSelectorItemProps
+) => <SelectItem {...props} />;
diff --git a/src/components/ai-elements/commit.tsx b/src/components/ai-elements/commit.tsx
new file mode 100644
index 0000000..fbc82d3
--- /dev/null
+++ b/src/components/ai-elements/commit.tsx
@@ -0,0 +1,452 @@
+"use client";
+
+import { Avatar, AvatarFallback } from "@/components/ui/avatar";
+import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import { cn } from "@/lib/utils";
+import {
+  CheckIcon,
+  CopyIcon,
+  FileIcon,
+  GitCommitIcon,
+  MinusIcon,
+  PlusIcon,
+} from "lucide-react";
+import type { ComponentProps, HTMLAttributes } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export type CommitProps = ComponentProps<typeof Collapsible>;
+
+export const Commit = ({ className, children, ...props }: CommitProps) => (
+  <Collapsible
+    className={cn("rounded-lg border bg-background", className)}
+    {...props}
+  >
+    {children}
+  </Collapsible>
+);
+
+export type CommitHeaderProps = ComponentProps<typeof CollapsibleTrigger>;
+
+export const CommitHeader = ({
+  className,
+  children,
+  ...props
+}: CommitHeaderProps) => (
+  <CollapsibleTrigger {...props} render={<div className={cn(
+            "group flex cursor-pointer items-center justify-between gap-4 p-3 text-left transition-colors hover:opacity-80",
+            className
+          )} />}>{children}</CollapsibleTrigger>
+);
+
+export type CommitHashProps = HTMLAttributes<HTMLSpanElement>;
+
+export const CommitHash = ({
+  className,
+  children,
+  ...props
+}: CommitHashProps) => (
+  <span className={cn("font-mono text-xs", className)} {...props}>
+    <GitCommitIcon className="mr-1 inline-block size-3" />
+    {children}
+  </span>
+);
+
+export type CommitMessageProps = HTMLAttributes<HTMLSpanElement>;
+
+export const CommitMessage = ({
+  className,
+  children,
+  ...props
+}: CommitMessageProps) => (
+  <span className={cn("font-medium text-sm", className)} {...props}>
+    {children}
+  </span>
+);
+
+export type CommitMetadataProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitMetadata = ({
+  className,
+  children,
+  ...props
+}: CommitMetadataProps) => (
+  <div
+    className={cn(
+      "flex items-center gap-2 text-muted-foreground text-xs",
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type CommitSeparatorProps = HTMLAttributes<HTMLSpanElement>;
+
+export const CommitSeparator = ({
+  className,
+  children,
+  ...props
+}: CommitSeparatorProps) => (
+  <span className={className} {...props}>
+    {children ?? "•"}
+  </span>
+);
+
+export type CommitInfoProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitInfo = ({
+  className,
+  children,
+  ...props
+}: CommitInfoProps) => (
+  <div className={cn("flex flex-1 flex-col", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type CommitAuthorProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitAuthor = ({
+  className,
+  children,
+  ...props
+}: CommitAuthorProps) => (
+  <div className={cn("flex items-center", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type CommitAuthorAvatarProps = ComponentProps<typeof Avatar> & {
+  initials: string;
+};
+
+export const CommitAuthorAvatar = ({
+  initials,
+  className,
+  ...props
+}: CommitAuthorAvatarProps) => (
+  <Avatar className={cn("size-8", className)} {...props}>
+    <AvatarFallback className="text-xs">{initials}</AvatarFallback>
+  </Avatar>
+);
+
+export type CommitTimestampProps = HTMLAttributes<HTMLTimeElement> & {
+  date: Date;
+};
+
+const relativeTimeFormat = new Intl.RelativeTimeFormat("en", {
+  numeric: "auto",
+});
+
+const formatRelativeDate = (date: Date) => {
+  const days = Math.round(
+    (date.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
+  );
+  return relativeTimeFormat.format(days, "day");
+};
+
+export const CommitTimestamp = ({
+  date,
+  className,
+  children,
+  ...props
+}: CommitTimestampProps) => {
+  const [formatted, setFormatted] = useState("");
+
+  const updateFormatted = useCallback(() => {
+    setFormatted(formatRelativeDate(date));
+  }, [date]);
+
+  useEffect(() => {
+    updateFormatted();
+  }, [updateFormatted]);
+
+  return (
+    <time
+      className={cn("text-xs", className)}
+      dateTime={date.toISOString()}
+      {...props}
+    >
+      {children ?? formatted}
+    </time>
+  );
+};
+
+export type CommitActionsProps = HTMLAttributes<HTMLDivElement>;
+
+const handleActionsClick = (e: React.MouseEvent) => e.stopPropagation();
+const handleActionsKeyDown = (e: React.KeyboardEvent) => e.stopPropagation();
+
+export const CommitActions = ({
+  className,
+  children,
+  ...props
+}: CommitActionsProps) => (
+  <div
+    className={cn("flex items-center gap-1", className)}
+    onClick={handleActionsClick}
+    onKeyDown={handleActionsKeyDown}
+    role="group"
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type CommitCopyButtonProps = ComponentProps<typeof Button> & {
+  hash: string;
+  onCopy?: () => void;
+  onError?: (error: Error) => void;
+  timeout?: number;
+};
+
+export const CommitCopyButton = ({
+  hash,
+  onCopy,
+  onError,
+  timeout = 2000,
+  children,
+  className,
+  ...props
+}: CommitCopyButtonProps) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const timeoutRef = useRef<number>(0);
+
+  const copyToClipboard = useCallback(async () => {
+    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+      onError?.(new Error("Clipboard API not available"));
+      return;
+    }
+
+    try {
+      if (!isCopied) {
+        await navigator.clipboard.writeText(hash);
+        setIsCopied(true);
+        onCopy?.();
+        timeoutRef.current = window.setTimeout(
+          () => setIsCopied(false),
+          timeout
+        );
+      }
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }, [hash, onCopy, onError, timeout, isCopied]);
+
+  useEffect(
+    () => () => {
+      window.clearTimeout(timeoutRef.current);
+    },
+    []
+  );
+
+  const Icon = isCopied ? CheckIcon : CopyIcon;
+
+  return (
+    <Button
+      className={cn("size-7 shrink-0", className)}
+      onClick={copyToClipboard}
+      size="icon"
+      variant="ghost"
+      {...props}
+    >
+      {children ?? <Icon size={14} />}
+    </Button>
+  );
+};
+
+export type CommitContentProps = ComponentProps<typeof CollapsibleContent>;
+
+export const CommitContent = ({
+  className,
+  children,
+  ...props
+}: CommitContentProps) => (
+  <CollapsibleContent className={cn("border-t p-3", className)} {...props}>
+    {children}
+  </CollapsibleContent>
+);
+
+export type CommitFilesProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitFiles = ({
+  className,
+  children,
+  ...props
+}: CommitFilesProps) => (
+  <div className={cn("space-y-1", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type CommitFileProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitFile = ({
+  className,
+  children,
+  ...props
+}: CommitFileProps) => (
+  <div
+    className={cn(
+      "flex items-center justify-between gap-2 rounded px-2 py-1 text-sm hover:bg-muted/50",
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type CommitFileInfoProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitFileInfo = ({
+  className,
+  children,
+  ...props
+}: CommitFileInfoProps) => (
+  <div className={cn("flex min-w-0 items-center gap-2", className)} {...props}>
+    {children}
+  </div>
+);
+
+const fileStatusStyles = {
+  added: "text-green-600 dark:text-green-400",
+  deleted: "text-red-600 dark:text-red-400",
+  modified: "text-yellow-600 dark:text-yellow-400",
+  renamed: "text-blue-600 dark:text-blue-400",
+};
+
+const fileStatusLabels = {
+  added: "A",
+  deleted: "D",
+  modified: "M",
+  renamed: "R",
+};
+
+export type CommitFileStatusProps = HTMLAttributes<HTMLSpanElement> & {
+  status: "added" | "modified" | "deleted" | "renamed";
+};
+
+export const CommitFileStatus = ({
+  status,
+  className,
+  children,
+  ...props
+}: CommitFileStatusProps) => (
+  <span
+    className={cn(
+      "font-medium font-mono text-xs",
+      fileStatusStyles[status],
+      className
+    )}
+    {...props}
+  >
+    {children ?? fileStatusLabels[status]}
+  </span>
+);
+
+export type CommitFileIconProps = ComponentProps<typeof FileIcon>;
+
+export const CommitFileIcon = ({
+  className,
+  ...props
+}: CommitFileIconProps) => (
+  <FileIcon
+    className={cn("size-3.5 shrink-0 text-muted-foreground", className)}
+    {...props}
+  />
+);
+
+export type CommitFilePathProps = HTMLAttributes<HTMLSpanElement>;
+
+export const CommitFilePath = ({
+  className,
+  children,
+  ...props
+}: CommitFilePathProps) => (
+  <span className={cn("truncate font-mono text-xs", className)} {...props}>
+    {children}
+  </span>
+);
+
+export type CommitFileChangesProps = HTMLAttributes<HTMLDivElement>;
+
+export const CommitFileChanges = ({
+  className,
+  children,
+  ...props
+}: CommitFileChangesProps) => (
+  <div
+    className={cn(
+      "flex shrink-0 items-center gap-1 font-mono text-xs",
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type CommitFileAdditionsProps = HTMLAttributes<HTMLSpanElement> & {
+  count: number;
+};
+
+export const CommitFileAdditions = ({
+  count,
+  className,
+  children,
+  ...props
+}: CommitFileAdditionsProps) => {
+  if (count <= 0) {
+    return null;
+  }
+
+  return (
+    <span
+      className={cn("text-green-600 dark:text-green-400", className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <PlusIcon className="inline-block size-3" />
+          {count}
+        </>
+      )}
+    </span>
+  );
+};
+
+export type CommitFileDeletionsProps = HTMLAttributes<HTMLSpanElement> & {
+  count: number;
+};
+
+export const CommitFileDeletions = ({
+  count,
+  className,
+  children,
+  ...props
+}: CommitFileDeletionsProps) => {
+  if (count <= 0) {
+    return null;
+  }
+
+  return (
+    <span
+      className={cn("text-red-600 dark:text-red-400", className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <MinusIcon className="inline-block size-3" />
+          {count}
+        </>
+      )}
+    </span>
+  );
+};
diff --git a/src/components/ai-elements/context.tsx b/src/components/ai-elements/context.tsx
new file mode 100644
index 0000000..f2f16f2
--- /dev/null
+++ b/src/components/ai-elements/context.tsx
@@ -0,0 +1,409 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+} from "@/components/ui/hover-card";
+import { Progress } from "@/components/ui/progress";
+import { cn } from "@/lib/utils";
+import type { LanguageModelUsage } from "ai";
+import type { ComponentProps } from "react";
+import { createContext, useContext, useMemo } from "react";
+import { getUsage } from "tokenlens";
+
+const PERCENT_MAX = 100;
+const ICON_RADIUS = 10;
+const ICON_VIEWBOX = 24;
+const ICON_CENTER = 12;
+const ICON_STROKE_WIDTH = 2;
+
+type ModelId = string;
+
+interface ContextSchema {
+  usedTokens: number;
+  maxTokens: number;
+  usage?: LanguageModelUsage;
+  modelId?: ModelId;
+}
+
+const ContextContext = createContext<ContextSchema | null>(null);
+
+const useContextValue = () => {
+  const context = useContext(ContextContext);
+
+  if (!context) {
+    throw new Error("Context components must be used within Context");
+  }
+
+  return context;
+};
+
+export type ContextProps = ComponentProps<typeof HoverCard> & ContextSchema;
+
+export const Context = ({
+  usedTokens,
+  maxTokens,
+  usage,
+  modelId,
+  ...props
+}: ContextProps) => {
+  const contextValue = useMemo(
+    () => ({ maxTokens, modelId, usage, usedTokens }),
+    [maxTokens, modelId, usage, usedTokens]
+  );
+
+  return (
+    <ContextContext.Provider value={contextValue}>
+      <HoverCard closeDelay={0} openDelay={0} {...props as any} />
+    </ContextContext.Provider>
+  );
+};
+
+const ContextIcon = () => {
+  const { usedTokens, maxTokens } = useContextValue();
+  const circumference = 2 * Math.PI * ICON_RADIUS;
+  const usedPercent = usedTokens / maxTokens;
+  const dashOffset = circumference * (1 - usedPercent);
+
+  return (
+    <svg
+      aria-label="Model context usage"
+      height="20"
+      role="img"
+      style={{ color: "currentcolor" }}
+      viewBox={`0 0 ${ICON_VIEWBOX} ${ICON_VIEWBOX}`}
+      width="20"
+    >
+      <circle
+        cx={ICON_CENTER}
+        cy={ICON_CENTER}
+        fill="none"
+        opacity="0.25"
+        r={ICON_RADIUS}
+        stroke="currentColor"
+        strokeWidth={ICON_STROKE_WIDTH}
+      />
+      <circle
+        cx={ICON_CENTER}
+        cy={ICON_CENTER}
+        fill="none"
+        opacity="0.7"
+        r={ICON_RADIUS}
+        stroke="currentColor"
+        strokeDasharray={`${circumference} ${circumference}`}
+        strokeDashoffset={dashOffset}
+        strokeLinecap="round"
+        strokeWidth={ICON_STROKE_WIDTH}
+        style={{ transform: "rotate(-90deg)", transformOrigin: "center" }}
+      />
+    </svg>
+  );
+};
+
+export type ContextTriggerProps = ComponentProps<typeof Button>;
+
+export const ContextTrigger = ({ children, ...props }: ContextTriggerProps) => {
+  const { usedTokens, maxTokens } = useContextValue();
+  const usedPercent = usedTokens / maxTokens;
+  const renderedPercent = new Intl.NumberFormat("en-US", {
+    maximumFractionDigits: 1,
+    style: "percent",
+  }).format(usedPercent);
+
+  return (
+    <HoverCardTrigger>
+      {children ?? (
+        <Button type="button" variant="ghost" {...props}>
+          <span className="font-medium text-muted-foreground">
+            {renderedPercent}
+          </span>
+          <ContextIcon />
+        </Button>
+      )}
+    </HoverCardTrigger>
+  );
+};
+
+export type ContextContentProps = ComponentProps<typeof HoverCardContent>;
+
+export const ContextContent = ({
+  className,
+  ...props
+}: ContextContentProps) => (
+  <HoverCardContent
+    className={cn("min-w-60 divide-y overflow-hidden p-0", className)}
+    {...props}
+  />
+);
+
+export type ContextContentHeaderProps = ComponentProps<"div">;
+
+export const ContextContentHeader = ({
+  children,
+  className,
+  ...props
+}: ContextContentHeaderProps) => {
+  const { usedTokens, maxTokens } = useContextValue();
+  const usedPercent = usedTokens / maxTokens;
+  const displayPct = new Intl.NumberFormat("en-US", {
+    maximumFractionDigits: 1,
+    style: "percent",
+  }).format(usedPercent);
+  const used = new Intl.NumberFormat("en-US", {
+    notation: "compact",
+  }).format(usedTokens);
+  const total = new Intl.NumberFormat("en-US", {
+    notation: "compact",
+  }).format(maxTokens);
+
+  return (
+    <div className={cn("w-full space-y-2 p-3", className)} {...props}>
+      {children ?? (
+        <>
+          <div className="flex items-center justify-between gap-3 text-xs">
+            <p>{displayPct}</p>
+            <p className="font-mono text-muted-foreground">
+              {used} / {total}
+            </p>
+          </div>
+          <div className="space-y-2">
+            <Progress className="bg-muted" value={usedPercent * PERCENT_MAX} />
+          </div>
+        </>
+      )}
+    </div>
+  );
+};
+
+export type ContextContentBodyProps = ComponentProps<"div">;
+
+export const ContextContentBody = ({
+  children,
+  className,
+  ...props
+}: ContextContentBodyProps) => (
+  <div className={cn("w-full p-3", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type ContextContentFooterProps = ComponentProps<"div">;
+
+export const ContextContentFooter = ({
+  children,
+  className,
+  ...props
+}: ContextContentFooterProps) => {
+  const { modelId, usage } = useContextValue();
+  const costUSD = modelId
+    ? getUsage({
+        modelId,
+        usage: {
+          input: usage?.inputTokens ?? 0,
+          output: usage?.outputTokens ?? 0,
+        },
+      }).costUSD?.totalUSD
+    : undefined;
+  const totalCost = new Intl.NumberFormat("en-US", {
+    currency: "USD",
+    style: "currency",
+  }).format(costUSD ?? 0);
+
+  return (
+    <div
+      className={cn(
+        "flex w-full items-center justify-between gap-3 bg-secondary p-3 text-xs",
+        className
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <span className="text-muted-foreground">Total cost</span>
+          <span>{totalCost}</span>
+        </>
+      )}
+    </div>
+  );
+};
+
+const TokensWithCost = ({
+  tokens,
+  costText,
+}: {
+  tokens?: number;
+  costText?: string;
+}) => (
+  <span>
+    {tokens === undefined
+      ? "—"
+      : new Intl.NumberFormat("en-US", {
+          notation: "compact",
+        }).format(tokens)}
+    {costText ? (
+      <span className="ml-2 text-muted-foreground">• {costText}</span>
+    ) : null}
+  </span>
+);
+
+export type ContextInputUsageProps = ComponentProps<"div">;
+
+export const ContextInputUsage = ({
+  className,
+  children,
+  ...props
+}: ContextInputUsageProps) => {
+  const { usage, modelId } = useContextValue();
+  const inputTokens = usage?.inputTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!inputTokens) {
+    return null;
+  }
+
+  const inputCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { input: inputTokens, output: 0 },
+      }).costUSD?.totalUSD
+    : undefined;
+  const inputCostText = new Intl.NumberFormat("en-US", {
+    currency: "USD",
+    style: "currency",
+  }).format(inputCost ?? 0);
+
+  return (
+    <div
+      className={cn("flex items-center justify-between text-xs", className)}
+      {...props}
+    >
+      <span className="text-muted-foreground">Input</span>
+      <TokensWithCost costText={inputCostText} tokens={inputTokens} />
+    </div>
+  );
+};
+
+export type ContextOutputUsageProps = ComponentProps<"div">;
+
+export const ContextOutputUsage = ({
+  className,
+  children,
+  ...props
+}: ContextOutputUsageProps) => {
+  const { usage, modelId } = useContextValue();
+  const outputTokens = usage?.outputTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!outputTokens) {
+    return null;
+  }
+
+  const outputCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { input: 0, output: outputTokens },
+      }).costUSD?.totalUSD
+    : undefined;
+  const outputCostText = new Intl.NumberFormat("en-US", {
+    currency: "USD",
+    style: "currency",
+  }).format(outputCost ?? 0);
+
+  return (
+    <div
+      className={cn("flex items-center justify-between text-xs", className)}
+      {...props}
+    >
+      <span className="text-muted-foreground">Output</span>
+      <TokensWithCost costText={outputCostText} tokens={outputTokens} />
+    </div>
+  );
+};
+
+export type ContextReasoningUsageProps = ComponentProps<"div">;
+
+export const ContextReasoningUsage = ({
+  className,
+  children,
+  ...props
+}: ContextReasoningUsageProps) => {
+  const { usage, modelId } = useContextValue();
+  const reasoningTokens = usage?.reasoningTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!reasoningTokens) {
+    return null;
+  }
+
+  const reasoningCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { reasoningTokens },
+      }).costUSD?.totalUSD
+    : undefined;
+  const reasoningCostText = new Intl.NumberFormat("en-US", {
+    currency: "USD",
+    style: "currency",
+  }).format(reasoningCost ?? 0);
+
+  return (
+    <div
+      className={cn("flex items-center justify-between text-xs", className)}
+      {...props}
+    >
+      <span className="text-muted-foreground">Reasoning</span>
+      <TokensWithCost costText={reasoningCostText} tokens={reasoningTokens} />
+    </div>
+  );
+};
+
+export type ContextCacheUsageProps = ComponentProps<"div">;
+
+export const ContextCacheUsage = ({
+  className,
+  children,
+  ...props
+}: ContextCacheUsageProps) => {
+  const { usage, modelId } = useContextValue();
+  const cacheTokens = usage?.cachedInputTokens ?? 0;
+
+  if (children) {
+    return children;
+  }
+
+  if (!cacheTokens) {
+    return null;
+  }
+
+  const cacheCost = modelId
+    ? getUsage({
+        modelId,
+        usage: { cacheReads: cacheTokens, input: 0, output: 0 },
+      }).costUSD?.totalUSD
+    : undefined;
+  const cacheCostText = new Intl.NumberFormat("en-US", {
+    currency: "USD",
+    style: "currency",
+  }).format(cacheCost ?? 0);
+
+  return (
+    <div
+      className={cn("flex items-center justify-between text-xs", className)}
+      {...props}
+    >
+      <span className="text-muted-foreground">Cache</span>
+      <TokensWithCost costText={cacheCostText} tokens={cacheTokens} />
+    </div>
+  );
+};
diff --git a/src/components/ai-elements/jsx-preview.tsx b/src/components/ai-elements/jsx-preview.tsx
new file mode 100644
index 0000000..2744d12
--- /dev/null
+++ b/src/components/ai-elements/jsx-preview.tsx
@@ -0,0 +1,310 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import { AlertCircle } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+import {
+  createContext,
+  memo,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { TProps as JsxParserProps } from "react-jsx-parser";
+import JsxParser from "react-jsx-parser";
+
+interface JSXPreviewContextValue {
+  jsx: string;
+  processedJsx: string;
+  isStreaming: boolean;
+  error: Error | null;
+  setError: (error: Error | null) => void;
+  setLastGoodJsx: (jsx: string) => void;
+  components: JsxParserProps["components"];
+  bindings: JsxParserProps["bindings"];
+  onErrorProp?: (error: Error) => void;
+}
+
+const JSXPreviewContext = createContext<JSXPreviewContextValue | null>(null);
+
+const TAG_REGEX = /<\/?([a-zA-Z][a-zA-Z0-9]*)\s*([^>]*?)(\/)?>/;
+
+export const useJSXPreview = () => {
+  const context = useContext(JSXPreviewContext);
+  if (!context) {
+    throw new Error("JSXPreview components must be used within JSXPreview");
+  }
+  return context;
+};
+
+const matchJsxTag = (code: string) => {
+  if (code.trim() === "") {
+    return null;
+  }
+
+  const match = code.match(TAG_REGEX);
+
+  if (!match || match.index === undefined) {
+    return null;
+  }
+
+  const [fullMatch, tagName, attributes, selfClosing] = match;
+
+  let type: "self-closing" | "closing" | "opening";
+  if (selfClosing) {
+    type = "self-closing";
+  } else if (fullMatch.startsWith("</")) {
+    type = "closing";
+  } else {
+    type = "opening";
+  }
+
+  return {
+    attributes: attributes.trim(),
+    endIndex: match.index + fullMatch.length,
+    startIndex: match.index,
+    tag: fullMatch,
+    tagName,
+    type,
+  };
+};
+
+const stripIncompleteTag = (text: string) => {
+  // Find the last '<' that isn't part of a complete tag
+  const lastOpen = text.lastIndexOf("<");
+  if (lastOpen === -1) {
+    return text;
+  }
+
+  const afterOpen = text.slice(lastOpen);
+  // If there's no closing '>' after the last '<', it's an incomplete tag
+  if (!afterOpen.includes(">")) {
+    return text.slice(0, lastOpen);
+  }
+
+  return text;
+};
+
+const completeJsxTag = (code: string) => {
+  const stack: string[] = [];
+  let result = "";
+  let currentPosition = 0;
+
+  while (currentPosition < code.length) {
+    const match = matchJsxTag(code.slice(currentPosition));
+    if (!match) {
+      // No more tags found, strip any trailing incomplete tag
+      result += stripIncompleteTag(code.slice(currentPosition));
+      break;
+    }
+    const { tagName, type, endIndex } = match;
+
+    // Include any text content before this tag
+    result += code.slice(currentPosition, currentPosition + endIndex);
+
+    if (type === "opening") {
+      stack.push(tagName);
+    } else if (type === "closing") {
+      stack.pop();
+    }
+
+    currentPosition += endIndex;
+  }
+
+  return (
+    result +
+    stack
+      .toReversed()
+      .map((tag) => `</${tag}>`)
+      .join("")
+  );
+};
+
+export type JSXPreviewProps = ComponentProps<"div"> & {
+  jsx: string;
+  isStreaming?: boolean;
+  components?: JsxParserProps["components"];
+  bindings?: JsxParserProps["bindings"];
+  onError?: (error: Error) => void;
+};
+
+export const JSXPreview = memo(
+  ({
+    jsx,
+    isStreaming = false,
+    components,
+    bindings,
+    onError,
+    className,
+    children,
+    ...props
+  }: JSXPreviewProps) => {
+    const [prevJsx, setPrevJsx] = useState(jsx);
+    const [error, setError] = useState<Error | null>(null);
+    const [_lastGoodJsx, setLastGoodJsx] = useState("");
+
+    // Clear error when jsx changes (derived state pattern)
+    if (jsx !== prevJsx) {
+      setPrevJsx(jsx);
+      setError(null);
+    }
+
+    const processedJsx = useMemo(
+      () => (isStreaming ? completeJsxTag(jsx) : jsx),
+      [jsx, isStreaming]
+    );
+
+    const contextValue = useMemo(
+      () => ({
+        bindings,
+        components,
+        error,
+        isStreaming,
+        jsx,
+        onErrorProp: onError,
+        processedJsx,
+        setError,
+        setLastGoodJsx,
+      }),
+      [
+        bindings,
+        components,
+        error,
+        isStreaming,
+        jsx,
+        onError,
+        processedJsx,
+        setError,
+      ]
+    );
+
+    return (
+      <JSXPreviewContext.Provider value={contextValue}>
+        <div className={cn("relative", className)} {...props}>
+          {children}
+        </div>
+      </JSXPreviewContext.Provider>
+    );
+  }
+);
+
+JSXPreview.displayName = "JSXPreview";
+
+export type JSXPreviewContentProps = Omit<ComponentProps<"div">, "children">;
+
+export const JSXPreviewContent = memo(
+  ({ className, ...props }: JSXPreviewContentProps) => {
+    const {
+      processedJsx,
+      isStreaming,
+      components,
+      bindings,
+      setError,
+      setLastGoodJsx,
+      onErrorProp,
+    } = useJSXPreview();
+    const errorReportedRef = useRef<string | null>(null);
+    const lastGoodJsxRef = useRef("");
+    const [hadError, setHadError] = useState(false);
+
+    // Reset error tracking when jsx changes
+    useEffect(() => {
+      errorReportedRef.current = null;
+      setHadError(false);
+    }, [processedJsx]);
+
+    const handleError = useCallback(
+      (err: Error) => {
+        // Prevent duplicate error reports for the same jsx
+        if (errorReportedRef.current === processedJsx) {
+          return;
+        }
+        errorReportedRef.current = processedJsx;
+
+        // During streaming, suppress errors and fall back to last good JSX
+        if (isStreaming) {
+          setHadError(true);
+          return;
+        }
+
+        setError(err);
+        onErrorProp?.(err);
+      },
+      [processedJsx, isStreaming, onErrorProp, setError]
+    );
+
+    // Track the last JSX that rendered without error
+    useEffect(() => {
+      if (!errorReportedRef.current) {
+        lastGoodJsxRef.current = processedJsx;
+        setLastGoodJsx(processedJsx);
+      }
+    }, [processedJsx, setLastGoodJsx]);
+
+    // During streaming, if the current JSX errored, re-render with last good version
+    const displayJsx =
+      isStreaming && hadError ? lastGoodJsxRef.current : processedJsx;
+
+    return (
+      <div className={cn("jsx-preview-content", className)} {...props}>
+        <JsxParser
+          bindings={bindings}
+          components={components}
+          jsx={displayJsx}
+          onError={handleError}
+          renderInWrapper={false}
+        />
+      </div>
+    );
+  }
+);
+
+JSXPreviewContent.displayName = "JSXPreviewContent";
+
+export type JSXPreviewErrorProps = ComponentProps<"div"> & {
+  children?: ReactNode | ((error: Error) => ReactNode);
+};
+
+const renderChildren = (
+  children: ReactNode | ((error: Error) => ReactNode),
+  error: Error
+): ReactNode => {
+  if (typeof children === "function") {
+    return children(error);
+  }
+  return children;
+};
+
+export const JSXPreviewError = memo(
+  ({ className, children, ...props }: JSXPreviewErrorProps) => {
+    const { error } = useJSXPreview();
+
+    if (!error) {
+      return null;
+    }
+
+    return (
+      <div
+        className={cn(
+          "flex items-center gap-2 rounded-md border border-destructive/50 bg-destructive/10 p-3 text-destructive text-sm",
+          className
+        )}
+        {...props}
+      >
+        {children ? (
+          renderChildren(children, error)
+        ) : (
+          <>
+            <AlertCircle className="size-4 shrink-0" />
+            <span>{error.message}</span>
+          </>
+        )}
+      </div>
+    );
+  }
+);
+
+JSXPreviewError.displayName = "JSXPreviewError";
diff --git a/src/components/ai-elements/package-info.tsx b/src/components/ai-elements/package-info.tsx
new file mode 100644
index 0000000..099c028
--- /dev/null
+++ b/src/components/ai-elements/package-info.tsx
@@ -0,0 +1,239 @@
+"use client";
+
+import { Badge } from "@/components/ui/badge";
+import { cn } from "@/lib/utils";
+import { ArrowRightIcon, MinusIcon, PackageIcon, PlusIcon } from "lucide-react";
+import type { HTMLAttributes } from "react";
+import { createContext, useContext, useMemo } from "react";
+
+type ChangeType = "major" | "minor" | "patch" | "added" | "removed";
+
+interface PackageInfoContextType {
+  name: string;
+  currentVersion?: string;
+  newVersion?: string;
+  changeType?: ChangeType;
+}
+
+const PackageInfoContext = createContext<PackageInfoContextType>({
+  name: "",
+});
+
+export type PackageInfoHeaderProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoHeader = ({
+  className,
+  children,
+  ...props
+}: PackageInfoHeaderProps) => (
+  <div
+    className={cn("flex items-center justify-between gap-2", className)}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type PackageInfoNameProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoName = ({
+  className,
+  children,
+  ...props
+}: PackageInfoNameProps) => {
+  const { name } = useContext(PackageInfoContext);
+
+  return (
+    <div className={cn("flex items-center gap-2", className)} {...props}>
+      <PackageIcon className="size-4 text-muted-foreground" />
+      <span className="font-medium font-mono text-sm">{children ?? name}</span>
+    </div>
+  );
+};
+
+const changeTypeStyles: Record<ChangeType, string> = {
+  added: "bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400",
+  major: "bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400",
+  minor:
+    "bg-yellow-100 text-yellow-700 dark:bg-yellow-900/30 dark:text-yellow-400",
+  patch: "bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400",
+  removed: "bg-gray-100 text-gray-700 dark:bg-gray-900/30 dark:text-gray-400",
+};
+
+const changeTypeIcons: Record<ChangeType, React.ReactNode> = {
+  added: <PlusIcon className="size-3" />,
+  major: <ArrowRightIcon className="size-3" />,
+  minor: <ArrowRightIcon className="size-3" />,
+  patch: <ArrowRightIcon className="size-3" />,
+  removed: <MinusIcon className="size-3" />,
+};
+
+export type PackageInfoChangeTypeProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoChangeType = ({
+  className,
+  children,
+  ...props
+}: PackageInfoChangeTypeProps) => {
+  const { changeType } = useContext(PackageInfoContext);
+
+  if (!changeType) {
+    return null;
+  }
+
+  return (
+    <Badge
+      className={cn(
+        "gap-1 text-xs capitalize",
+        changeTypeStyles[changeType],
+        className
+      )}
+      variant="secondary"
+      {...props}
+    >
+      {changeTypeIcons[changeType]}
+      {children ?? changeType}
+    </Badge>
+  );
+};
+
+export type PackageInfoVersionProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoVersion = ({
+  className,
+  children,
+  ...props
+}: PackageInfoVersionProps) => {
+  const { currentVersion, newVersion } = useContext(PackageInfoContext);
+
+  if (!(currentVersion || newVersion)) {
+    return null;
+  }
+
+  return (
+    <div
+      className={cn(
+        "mt-2 flex items-center gap-2 font-mono text-muted-foreground text-sm",
+        className
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          {currentVersion && <span>{currentVersion}</span>}
+          {currentVersion && newVersion && (
+            <ArrowRightIcon className="size-3" />
+          )}
+          {newVersion && (
+            <span className="font-medium text-foreground">{newVersion}</span>
+          )}
+        </>
+      )}
+    </div>
+  );
+};
+
+export type PackageInfoProps = HTMLAttributes<HTMLDivElement> & {
+  name: string;
+  currentVersion?: string;
+  newVersion?: string;
+  changeType?: ChangeType;
+};
+
+export const PackageInfo = ({
+  name,
+  currentVersion,
+  newVersion,
+  changeType,
+  className,
+  children,
+  ...props
+}: PackageInfoProps) => {
+  const contextValue = useMemo(
+    () => ({ changeType, currentVersion, name, newVersion }),
+    [changeType, currentVersion, name, newVersion]
+  );
+
+  return (
+    <PackageInfoContext.Provider value={contextValue}>
+      <div
+        className={cn("rounded-lg border bg-background p-4", className)}
+        {...props}
+      >
+        {children ?? (
+          <>
+            <PackageInfoHeader>
+              <PackageInfoName />
+              {changeType && <PackageInfoChangeType />}
+            </PackageInfoHeader>
+            {(currentVersion || newVersion) && <PackageInfoVersion />}
+          </>
+        )}
+      </div>
+    </PackageInfoContext.Provider>
+  );
+};
+
+export type PackageInfoDescriptionProps = HTMLAttributes<HTMLParagraphElement>;
+
+export const PackageInfoDescription = ({
+  className,
+  children,
+  ...props
+}: PackageInfoDescriptionProps) => (
+  <p className={cn("mt-2 text-muted-foreground text-sm", className)} {...props}>
+    {children}
+  </p>
+);
+
+export type PackageInfoContentProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoContent = ({
+  className,
+  children,
+  ...props
+}: PackageInfoContentProps) => (
+  <div className={cn("mt-3 border-t pt-3", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type PackageInfoDependenciesProps = HTMLAttributes<HTMLDivElement>;
+
+export const PackageInfoDependencies = ({
+  className,
+  children,
+  ...props
+}: PackageInfoDependenciesProps) => (
+  <div className={cn("space-y-2", className)} {...props}>
+    <span className="font-medium text-muted-foreground text-xs uppercase tracking-wide">
+      Dependencies
+    </span>
+    <div className="space-y-1">{children}</div>
+  </div>
+);
+
+export type PackageInfoDependencyProps = HTMLAttributes<HTMLDivElement> & {
+  name: string;
+  version?: string;
+};
+
+export const PackageInfoDependency = ({
+  name,
+  version,
+  className,
+  children,
+  ...props
+}: PackageInfoDependencyProps) => (
+  <div
+    className={cn("flex items-center justify-between text-sm", className)}
+    {...props}
+  >
+    {children ?? (
+      <>
+        <span className="font-mono text-muted-foreground">{name}</span>
+        {version && <span className="font-mono text-xs">{version}</span>}
+      </>
+    )}
+  </div>
+);
diff --git a/src/components/ai-elements/snippet.tsx b/src/components/ai-elements/snippet.tsx
new file mode 100644
index 0000000..2d2b915
--- /dev/null
+++ b/src/components/ai-elements/snippet.tsx
@@ -0,0 +1,145 @@
+"use client";
+
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+} from "@/components/ui/input-group";
+import { cn } from "@/lib/utils";
+import { CheckIcon, CopyIcon } from "lucide-react";
+import type { ComponentProps } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+interface SnippetContextType {
+  code: string;
+}
+
+const SnippetContext = createContext<SnippetContextType>({
+  code: "",
+});
+
+export type SnippetProps = ComponentProps<typeof InputGroup> & {
+  code: string;
+};
+
+export const Snippet = ({
+  code,
+  className,
+  children,
+  ...props
+}: SnippetProps) => {
+  const contextValue = useMemo(() => ({ code }), [code]);
+
+  return (
+    <SnippetContext.Provider value={contextValue}>
+      <InputGroup className={cn("font-mono", className)} {...props}>
+        {children}
+      </InputGroup>
+    </SnippetContext.Provider>
+  );
+};
+
+export type SnippetAddonProps = ComponentProps<typeof InputGroupAddon>;
+
+export const SnippetAddon = (props: SnippetAddonProps) => (
+  <InputGroupAddon {...props} />
+);
+
+export type SnippetTextProps = ComponentProps<typeof InputGroupText>;
+
+export const SnippetText = ({ className, ...props }: SnippetTextProps) => (
+  <InputGroupText
+    className={cn("pl-2 font-normal text-muted-foreground", className)}
+    {...props}
+  />
+);
+
+export type SnippetInputProps = Omit<
+  ComponentProps<typeof InputGroupInput>,
+  "readOnly" | "value"
+>;
+
+export const SnippetInput = ({ className, ...props }: SnippetInputProps) => {
+  const { code } = useContext(SnippetContext);
+
+  return (
+    <InputGroupInput
+      className={cn("text-foreground", className)}
+      readOnly
+      value={code}
+      {...props}
+    />
+  );
+};
+
+export type SnippetCopyButtonProps = ComponentProps<typeof InputGroupButton> & {
+  onCopy?: () => void;
+  onError?: (error: Error) => void;
+  timeout?: number;
+};
+
+export const SnippetCopyButton = ({
+  onCopy,
+  onError,
+  timeout = 2000,
+  children,
+  className,
+  ...props
+}: SnippetCopyButtonProps) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const timeoutRef = useRef<number>(0);
+  const { code } = useContext(SnippetContext);
+
+  const copyToClipboard = useCallback(async () => {
+    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+      onError?.(new Error("Clipboard API not available"));
+      return;
+    }
+
+    try {
+      if (!isCopied) {
+        await navigator.clipboard.writeText(code);
+        setIsCopied(true);
+        onCopy?.();
+        timeoutRef.current = window.setTimeout(
+          () => setIsCopied(false),
+          timeout
+        );
+      }
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }, [code, onCopy, onError, timeout, isCopied]);
+
+  useEffect(
+    () => () => {
+      window.clearTimeout(timeoutRef.current);
+    },
+    []
+  );
+
+  const Icon = isCopied ? CheckIcon : CopyIcon;
+
+  return (
+    <InputGroupButton
+      aria-label="Copy"
+      className={className}
+      onClick={copyToClipboard}
+      size="icon-sm"
+      title="Copy"
+      {...props}
+    >
+      {children ?? <Icon className="size-3.5" size={14} />}
+    </InputGroupButton>
+  );
+};
diff --git a/src/components/ai-elements/terminal.tsx b/src/components/ai-elements/terminal.tsx
new file mode 100644
index 0000000..17f127e
--- /dev/null
+++ b/src/components/ai-elements/terminal.tsx
@@ -0,0 +1,273 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import Ansi from "ansi-to-react";
+import { CheckIcon, CopyIcon, TerminalIcon, Trash2Icon } from "lucide-react";
+import type { ComponentProps, HTMLAttributes } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+interface TerminalContextType {
+  output: string;
+  isStreaming: boolean;
+  autoScroll: boolean;
+  onClear?: () => void;
+}
+
+const TerminalContext = createContext<TerminalContextType>({
+  autoScroll: true,
+  isStreaming: false,
+  output: "",
+});
+
+export type TerminalHeaderProps = HTMLAttributes<HTMLDivElement>;
+
+export const TerminalHeader = ({
+  className,
+  children,
+  ...props
+}: TerminalHeaderProps) => (
+  <div
+    className={cn(
+      "flex items-center justify-between border-zinc-800 border-b px-4 py-2",
+      className
+    )}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type TerminalTitleProps = HTMLAttributes<HTMLDivElement>;
+
+export const TerminalTitle = ({
+  className,
+  children,
+  ...props
+}: TerminalTitleProps) => (
+  <div
+    className={cn("flex items-center gap-2 text-sm text-zinc-400", className)}
+    {...props}
+  >
+    <TerminalIcon className="size-4" />
+    {children ?? "Terminal"}
+  </div>
+);
+
+export type TerminalStatusProps = HTMLAttributes<HTMLDivElement>;
+
+export const TerminalStatus = ({
+  className,
+  children,
+  ...props
+}: TerminalStatusProps) => {
+  const { isStreaming } = useContext(TerminalContext);
+
+  if (!isStreaming) {
+    return null;
+  }
+
+  return (
+    <div
+      className={cn("flex items-center gap-2 text-xs text-zinc-400", className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export type TerminalActionsProps = HTMLAttributes<HTMLDivElement>;
+
+export const TerminalActions = ({
+  className,
+  children,
+  ...props
+}: TerminalActionsProps) => (
+  <div className={cn("flex items-center gap-1", className)} {...props}>
+    {children}
+  </div>
+);
+
+export type TerminalCopyButtonProps = ComponentProps<typeof Button> & {
+  onCopy?: () => void;
+  onError?: (error: Error) => void;
+  timeout?: number;
+};
+
+export const TerminalCopyButton = ({
+  onCopy,
+  onError,
+  timeout = 2000,
+  children,
+  className,
+  ...props
+}: TerminalCopyButtonProps) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const timeoutRef = useRef<number>(0);
+  const { output } = useContext(TerminalContext);
+
+  const copyToClipboard = useCallback(async () => {
+    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+      onError?.(new Error("Clipboard API not available"));
+      return;
+    }
+
+    try {
+      await navigator.clipboard.writeText(output);
+      setIsCopied(true);
+      onCopy?.();
+      timeoutRef.current = window.setTimeout(() => setIsCopied(false), timeout);
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }, [output, onCopy, onError, timeout]);
+
+  useEffect(
+    () => () => {
+      window.clearTimeout(timeoutRef.current);
+    },
+    []
+  );
+
+  const Icon = isCopied ? CheckIcon : CopyIcon;
+
+  return (
+    <Button
+      className={cn(
+        "size-7 shrink-0 text-zinc-400 hover:bg-zinc-800 hover:text-zinc-100",
+        className
+      )}
+      onClick={copyToClipboard}
+      size="icon"
+      variant="ghost"
+      {...props}
+    >
+      {children ?? <Icon size={14} />}
+    </Button>
+  );
+};
+
+export type TerminalClearButtonProps = ComponentProps<typeof Button>;
+
+export const TerminalClearButton = ({
+  children,
+  className,
+  ...props
+}: TerminalClearButtonProps) => {
+  const { onClear } = useContext(TerminalContext);
+
+  if (!onClear) {
+    return null;
+  }
+
+  return (
+    <Button
+      className={cn(
+        "size-7 shrink-0 text-zinc-400 hover:bg-zinc-800 hover:text-zinc-100",
+        className
+      )}
+      onClick={onClear}
+      size="icon"
+      variant="ghost"
+      {...props}
+    >
+      {children ?? <Trash2Icon size={14} />}
+    </Button>
+  );
+};
+
+export type TerminalContentProps = HTMLAttributes<HTMLDivElement>;
+
+export const TerminalContent = ({
+  className,
+  children,
+  ...props
+}: TerminalContentProps) => {
+  const { output, isStreaming, autoScroll } = useContext(TerminalContext);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (autoScroll && containerRef.current) {
+      containerRef.current.scrollTop = containerRef.current.scrollHeight;
+    }
+  }, [output, autoScroll]);
+
+  return (
+    <div
+      className={cn(
+        "max-h-96 overflow-auto p-4 font-mono text-sm leading-relaxed",
+        className
+      )}
+      ref={containerRef}
+      {...props}
+    >
+      {children ?? (
+        <pre className="whitespace-pre-wrap break-words">
+          <Ansi>{output}</Ansi>
+          {isStreaming && (
+            <span className="ml-0.5 inline-block h-4 w-2 animate-pulse bg-zinc-100" />
+          )}
+        </pre>
+      )}
+    </div>
+  );
+};
+
+export type TerminalProps = HTMLAttributes<HTMLDivElement> & {
+  output: string;
+  isStreaming?: boolean;
+  autoScroll?: boolean;
+  onClear?: () => void;
+};
+
+export const Terminal = ({
+  output,
+  isStreaming = false,
+  autoScroll = true,
+  onClear,
+  className,
+  children,
+  ...props
+}: TerminalProps) => {
+  const contextValue = useMemo(
+    () => ({ autoScroll, isStreaming, onClear, output }),
+    [autoScroll, isStreaming, onClear, output]
+  );
+
+  return (
+    <TerminalContext.Provider value={contextValue}>
+      <div
+        className={cn(
+          "flex flex-col overflow-hidden rounded-lg border bg-zinc-950 text-zinc-100",
+          className
+        )}
+        {...props}
+      >
+        {children ?? (
+          <>
+            <TerminalHeader>
+              <TerminalTitle />
+              <div className="flex items-center gap-1">
+                <TerminalStatus />
+                <TerminalActions>
+                  <TerminalCopyButton />
+                  {onClear && <TerminalClearButton />}
+                </TerminalActions>
+              </div>
+            </TerminalHeader>
+            <TerminalContent />
+          </>
+        )}
+      </div>
+    </TerminalContext.Provider>
+  );
+};
diff --git a/src/components/ai-elements/tool.tsx b/src/components/ai-elements/tool.tsx
new file mode 100644
index 0000000..18c4bb8
--- /dev/null
+++ b/src/components/ai-elements/tool.tsx
@@ -0,0 +1,173 @@
+"use client";
+
+import { Badge } from "@/components/ui/badge";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import { cn } from "@/lib/utils";
+import type { DynamicToolUIPart, ToolUIPart } from "ai";
+import {
+  CheckCircleIcon,
+  ChevronDownIcon,
+  CircleIcon,
+  ClockIcon,
+  WrenchIcon,
+  XCircleIcon,
+} from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+import { isValidElement } from "react";
+
+import { CodeBlock } from "./code-block";
+
+export type ToolProps = ComponentProps<typeof Collapsible>;
+
+export const Tool = ({ className, ...props }: ToolProps) => (
+  <Collapsible
+    className={cn("group not-prose mb-4 w-full rounded-md border", className)}
+    {...props}
+  />
+);
+
+export type ToolPart = ToolUIPart | DynamicToolUIPart;
+
+export type ToolHeaderProps = {
+  title?: string;
+  className?: string;
+} & (
+  | { type: ToolUIPart["type"]; state: ToolUIPart["state"]; toolName?: never }
+  | {
+      type: DynamicToolUIPart["type"];
+      state: DynamicToolUIPart["state"];
+      toolName: string;
+    }
+);
+
+const statusLabels: Record<ToolPart["state"], string> = {
+  "approval-requested": "Awaiting Approval",
+  "approval-responded": "Responded",
+  "input-available": "Running",
+  "input-streaming": "Pending",
+  "output-available": "Completed",
+  "output-denied": "Denied",
+  "output-error": "Error",
+};
+
+const statusIcons: Record<ToolPart["state"], ReactNode> = {
+  "approval-requested": <ClockIcon className="size-4 text-yellow-600" />,
+  "approval-responded": <CheckCircleIcon className="size-4 text-blue-600" />,
+  "input-available": <ClockIcon className="size-4 animate-pulse" />,
+  "input-streaming": <CircleIcon className="size-4" />,
+  "output-available": <CheckCircleIcon className="size-4 text-green-600" />,
+  "output-denied": <XCircleIcon className="size-4 text-orange-600" />,
+  "output-error": <XCircleIcon className="size-4 text-red-600" />,
+};
+
+export const getStatusBadge = (status: ToolPart["state"]) => (
+  <Badge className="gap-1.5 rounded-full text-xs" variant="secondary">
+    {statusIcons[status]}
+    {statusLabels[status]}
+  </Badge>
+);
+
+export const ToolHeader = ({
+  className,
+  title,
+  type,
+  state,
+  toolName,
+  ...props
+}: ToolHeaderProps) => {
+  const derivedName =
+    type === "dynamic-tool" ? toolName : type.split("-").slice(1).join("-");
+
+  return (
+    <CollapsibleTrigger
+      className={cn(
+        "flex w-full items-center justify-between gap-4 p-3",
+        className
+      )}
+      {...props}
+    >
+      <div className="flex items-center gap-2">
+        <WrenchIcon className="size-4 text-muted-foreground" />
+        <span className="font-medium text-sm">{title ?? derivedName}</span>
+        {getStatusBadge(state)}
+      </div>
+      <ChevronDownIcon className="size-4 text-muted-foreground transition-transform group-data-[state=open]:rotate-180" />
+    </CollapsibleTrigger>
+  );
+};
+
+export type ToolContentProps = ComponentProps<typeof CollapsibleContent>;
+
+export const ToolContent = ({ className, ...props }: ToolContentProps) => (
+  <CollapsibleContent
+    className={cn(
+      "data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-top-2 data-[state=open]:slide-in-from-top-2 space-y-4 p-4 text-popover-foreground outline-none data-[state=closed]:animate-out data-[state=open]:animate-in",
+      className
+    )}
+    {...props}
+  />
+);
+
+export type ToolInputProps = ComponentProps<"div"> & {
+  input: ToolPart["input"];
+};
+
+export const ToolInput = ({ className, input, ...props }: ToolInputProps) => (
+  <div className={cn("space-y-2 overflow-hidden", className)} {...props}>
+    <h4 className="font-medium text-muted-foreground text-xs uppercase tracking-wide">
+      Parameters
+    </h4>
+    <div className="rounded-md bg-muted/50">
+      <CodeBlock code={JSON.stringify(input, null, 2)} language="json" />
+    </div>
+  </div>
+);
+
+export type ToolOutputProps = ComponentProps<"div"> & {
+  output: ToolPart["output"];
+  errorText: ToolPart["errorText"];
+};
+
+export const ToolOutput = ({
+  className,
+  output,
+  errorText,
+  ...props
+}: ToolOutputProps) => {
+  if (!(output || errorText)) {
+    return null;
+  }
+
+  let Output = <div>{output as ReactNode}</div>;
+
+  if (typeof output === "object" && !isValidElement(output)) {
+    Output = (
+      <CodeBlock code={JSON.stringify(output, null, 2)} language="json" />
+    );
+  } else if (typeof output === "string") {
+    Output = <CodeBlock code={output} language="json" />;
+  }
+
+  return (
+    <div className={cn("space-y-2", className)} {...props}>
+      <h4 className="font-medium text-muted-foreground text-xs uppercase tracking-wide">
+        {errorText ? "Error" : "Result"}
+      </h4>
+      <div
+        className={cn(
+          "overflow-x-auto rounded-md text-xs [&_table]:w-full",
+          errorText
+            ? "bg-destructive/10 text-destructive"
+            : "bg-muted/50 text-foreground"
+        )}
+      >
+        {errorText && <div>{errorText}</div>}
+        {Output}
+      </div>
+    </div>
+  );
+};
diff --git a/src/components/ai-elements/web-preview.tsx b/src/components/ai-elements/web-preview.tsx
new file mode 100644
index 0000000..350c6a6
--- /dev/null
+++ b/src/components/ai-elements/web-preview.tsx
@@ -0,0 +1,263 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible";
+import { Input } from "@/components/ui/input";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import { ChevronDownIcon } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from "react";
+
+export interface WebPreviewContextValue {
+  url: string;
+  setUrl: (url: string) => void;
+  consoleOpen: boolean;
+  setConsoleOpen: (open: boolean) => void;
+}
+
+const WebPreviewContext = createContext<WebPreviewContextValue | null>(null);
+
+const useWebPreview = () => {
+  const context = useContext(WebPreviewContext);
+  if (!context) {
+    throw new Error("WebPreview components must be used within a WebPreview");
+  }
+  return context;
+};
+
+export type WebPreviewProps = ComponentProps<"div"> & {
+  defaultUrl?: string;
+  onUrlChange?: (url: string) => void;
+};
+
+export const WebPreview = ({
+  className,
+  children,
+  defaultUrl = "",
+  onUrlChange,
+  ...props
+}: WebPreviewProps) => {
+  const [url, setUrl] = useState(defaultUrl);
+  const [consoleOpen, setConsoleOpen] = useState(false);
+
+  const handleUrlChange = useCallback(
+    (newUrl: string) => {
+      setUrl(newUrl);
+      onUrlChange?.(newUrl);
+    },
+    [onUrlChange]
+  );
+
+  const contextValue = useMemo<WebPreviewContextValue>(
+    () => ({
+      consoleOpen,
+      setConsoleOpen,
+      setUrl: handleUrlChange,
+      url,
+    }),
+    [consoleOpen, handleUrlChange, url]
+  );
+
+  return (
+    <WebPreviewContext.Provider value={contextValue}>
+      <div
+        className={cn(
+          "flex size-full flex-col rounded-lg border bg-card",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </WebPreviewContext.Provider>
+  );
+};
+
+export type WebPreviewNavigationProps = ComponentProps<"div">;
+
+export const WebPreviewNavigation = ({
+  className,
+  children,
+  ...props
+}: WebPreviewNavigationProps) => (
+  <div
+    className={cn("flex items-center gap-1 border-b p-2", className)}
+    {...props}
+  >
+    {children}
+  </div>
+);
+
+export type WebPreviewNavigationButtonProps = ComponentProps<typeof Button> & {
+  tooltip?: string;
+};
+
+export const WebPreviewNavigationButton = ({
+  onClick,
+  disabled,
+  tooltip,
+  children,
+  ...props
+}: WebPreviewNavigationButtonProps) => (
+  <TooltipProvider>
+    <Tooltip>
+      <TooltipTrigger render={<Button className="h-8 w-8 p-0 hover:text-foreground" disabled={disabled} onClick={onClick} size="sm" variant="ghost" {...props} />}>{children}</TooltipTrigger>
+      <TooltipContent>
+        <p>{tooltip}</p>
+      </TooltipContent>
+    </Tooltip>
+  </TooltipProvider>
+);
+
+export type WebPreviewUrlProps = ComponentProps<typeof Input>;
+
+export const WebPreviewUrl = ({
+  value,
+  onChange,
+  onKeyDown,
+  ...props
+}: WebPreviewUrlProps) => {
+  const { url, setUrl } = useWebPreview();
+  const [prevUrl, setPrevUrl] = useState(url);
+  const [inputValue, setInputValue] = useState(url);
+
+  // Sync input value with context URL when it changes externally (derived state pattern)
+  if (url !== prevUrl) {
+    setPrevUrl(url);
+    setInputValue(url);
+  }
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setInputValue(event.target.value);
+    onChange?.(event);
+  };
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "Enter") {
+        const target = event.target as HTMLInputElement;
+        setUrl(target.value);
+      }
+      onKeyDown?.(event);
+    },
+    [setUrl, onKeyDown]
+  );
+
+  return (
+    <Input
+      className="h-8 flex-1 text-sm"
+      onChange={onChange ?? handleChange}
+      onKeyDown={handleKeyDown}
+      placeholder="Enter URL..."
+      value={value ?? inputValue}
+      {...props}
+    />
+  );
+};
+
+export type WebPreviewBodyProps = ComponentProps<"iframe"> & {
+  loading?: ReactNode;
+};
+
+export const WebPreviewBody = ({
+  className,
+  loading,
+  src,
+  ...props
+}: WebPreviewBodyProps) => {
+  const { url } = useWebPreview();
+
+  return (
+    <div className="flex-1">
+      <iframe
+        className={cn("size-full", className)}
+        // oxlint-disable-next-line eslint-plugin-react(iframe-missing-sandbox)
+        sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-presentation"
+        src={(src ?? url) || undefined}
+        title="Preview"
+        {...props}
+      />
+      {loading}
+    </div>
+  );
+};
+
+export type WebPreviewConsoleProps = ComponentProps<"div"> & {
+  logs?: {
+    level: "log" | "warn" | "error";
+    message: string;
+    timestamp: Date;
+  }[];
+};
+
+export const WebPreviewConsole = ({
+  className,
+  logs = [],
+  children,
+  ...props
+}: WebPreviewConsoleProps) => {
+  const { consoleOpen, setConsoleOpen } = useWebPreview();
+
+  return (
+    <Collapsible
+      className={cn("border-t bg-muted/50 font-mono text-sm", className)}
+      onOpenChange={setConsoleOpen}
+      open={consoleOpen}
+      {...props}
+    >
+      <CollapsibleTrigger render={<Button className="flex w-full items-center justify-between p-4 text-left font-medium hover:bg-muted/50" variant="ghost" />}>Console
+                    <ChevronDownIcon
+                      className={cn(
+                        "h-4 w-4 transition-transform duration-200",
+                        consoleOpen && "rotate-180"
+                      )}
+                    /></CollapsibleTrigger>
+      <CollapsibleContent
+        className={cn(
+          "px-4 pb-4",
+          "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 outline-none data-[state=closed]:animate-out data-[state=open]:animate-in"
+        )}
+      >
+        <div className="max-h-48 space-y-1 overflow-y-auto">
+          {logs.length === 0 ? (
+            <p className="text-muted-foreground">No console output</p>
+          ) : (
+            logs.map((log) => (
+              <div
+                className={cn(
+                  "text-xs",
+                  log.level === "error" && "text-destructive",
+                  log.level === "warn" && "text-yellow-600",
+                  log.level === "log" && "text-foreground"
+                )}
+                key={`${log.timestamp.getTime()}-${log.level}-${log.message}`}
+              >
+                <span className="text-muted-foreground">
+                  {log.timestamp.toLocaleTimeString()}
+                </span>{" "}
+                {log.message}
+              </div>
+            ))
+          )}
+          {children}
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+};
diff --git a/src/components/shell/navshell.tsx b/src/components/shell/navshell.tsx
new file mode 100644
index 0000000..31935a3
--- /dev/null
+++ b/src/components/shell/navshell.tsx
@@ -0,0 +1,5 @@
+export { default as NavShell, WorkspaceRail } from "./rail";
+export { WorkspaceShell } from "./workspace-sidebar";
+export { PersonalShell } from "./personal-sidebar";
+export { SettingsShell } from "./settings-sidebar";
+export { type ShellNavItem, ShellNavLink, workspaceColor, workspaceInitial } from "./shared";
\ No newline at end of file
diff --git a/src/components/shell/personal-sidebar.tsx b/src/components/shell/personal-sidebar.tsx
new file mode 100644
index 0000000..0e928e0
--- /dev/null
+++ b/src/components/shell/personal-sidebar.tsx
@@ -0,0 +1,376 @@
+import { Link, Outlet, useLocation, useNavigate } from "react-router";
+import {
+  Bell,
+  ChevronDown,
+  Folder,
+  Grid2X2,
+  LayoutDashboard,
+  Search,
+  Sparkles,
+  Star,
+  Trash2,
+  Users,
+  Plus,
+  Bot,
+} from "lucide-react";
+import { useState, useEffect, useCallback } from "react";
+import { motion, AnimatePresence } from "motion/react";
+import { cn } from "@/lib/utils";
+import NavShell from "./rail";
+import { workspaceColor, workspaceInitial } from "./shared";
+import { useAuth } from "@/context/auth-context";
+import { Button } from "@/components/ui/button";
+import { client } from "@/client";
+import type { ConversationWithSessionResponse } from "@/client/models/conversationWithSessionResponse";
+import { Shimmer } from "@/components/ai-elements/shimmer";
+import { usePersonalSessions, ensurePersonalSession } from "@/page/me/chat/use-personal-sessions";
+
+function PersonalAvatar() {
+  const { me } = useAuth();
+  const name = me?.display_name || me?.username || "User";
+
+  return (
+    <span
+      className={cn(
+        "grid size-9 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-sm font-semibold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {me?.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={me.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+function PersonalModeSwitch() {
+  const location = useLocation();
+  const showAgent = location.pathname.startsWith("/me/chat");
+
+  const modes = [
+    { label: "Agent", to: "/me/chat", icon: <Sparkles className="size-4" />, active: showAgent },
+    { label: "Personal", to: "/me", icon: <Grid2X2 className="size-4" />, active: !showAgent },
+  ];
+
+  return (
+    <nav aria-label="Personal mode" className="grid grid-cols-2 gap-1 rounded-xl bg-muted/70 p-1">
+      {modes.map((mode) => (
+        <Link
+          className={cn(
+            "flex h-8 items-center justify-center gap-2 rounded-md text-sm font-semibold text-muted-foreground transition-colors hover:text-foreground",
+            mode.active && "bg-card text-foreground shadow-sm ring-1 ring-border",
+          )}
+          key={mode.to}
+          to={mode.to}
+        >
+          {mode.icon}
+          <span className="truncate">{mode.label}</span>
+        </Link>
+      ))}
+    </nav>
+  );
+}
+
+function PersonalNavLink({ item, active }: { item: { label: string; to: string; icon: React.ReactNode; badge?: string }; active: boolean }) {
+  return (
+    <Link
+      className={cn(
+        "flex h-9 items-center gap-2.5 rounded-lg px-3 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
+        active && "bg-accent text-foreground",
+      )}
+      to={item.to}
+    >
+      <span className="text-muted-foreground [&_svg]:size-4">{item.icon}</span>
+      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+      {item.badge && (
+        <span className="rounded-full bg-card px-2 py-0.5 text-xs text-muted-foreground">{item.badge}</span>
+      )}
+    </Link>
+  );
+}
+
+// ---- Agent Chat Section (replaces DMs) ----
+
+function formatTime(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffDays = Math.floor(diffMs / 86_400_000);
+  if (diffDays === 0) return d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  if (diffDays === 1) return "Yesterday";
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return d.toLocaleDateString([], { month: "short", day: "numeric" });
+}
+
+const SKELETON_COUNT = 3;
+
+function AgentChatSidebar() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const conversationId = location.pathname.split("/me/chat/")[1] || "";
+  const { sessions, loading: sessionsLoading, sessionsRef, personalSessionIds } = usePersonalSessions();
+
+  const [conversations, setConversations] = useState<ConversationWithSessionResponse[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  const loadConversations = useCallback(async () => {
+    if (personalSessionIds.size === 0) return;
+    try {
+      setLoading(true);
+      const res = await client.agentListAllConversations().catch(() => ({
+        data: [] as ConversationWithSessionResponse[],
+      }));
+      const sorted = [...res.data]
+        .filter((c) => personalSessionIds.has(c.session_id))
+        .sort((a, b) => {
+        const da = a.last_message_at ? new Date(a.last_message_at).getTime() : new Date(a.created_at).getTime();
+        const db = b.last_message_at ? new Date(b.last_message_at).getTime() : new Date(b.created_at).getTime();
+        return db - da;
+      });
+      setConversations(sorted);
+    } finally {
+      setLoading(false);
+    }
+  }, [personalSessionIds]);
+
+  // Only load conversations after personal sessions are known
+  useEffect(() => {
+    if (!sessionsLoading) {
+      loadConversations();
+    }
+  }, [sessionsLoading, loadConversations]);
+
+  const handleNewChat = useCallback(async () => {
+    const sessionId = await ensurePersonalSession(sessionsRef.current);
+    if (!sessionId) return;
+
+    try {
+      const res = await client.agentCreateConversation(sessionId, { title: "New Chat" });
+      const conv = res.data as unknown as ConversationWithSessionResponse;
+      setConversations((prev) => [conv, ...prev]);
+      navigate(`/me/chat/${conv.id}`);
+    } catch {
+      // Silently fail.
+    }
+  }, [sessionsRef, navigate]);
+
+  const handleDelete = useCallback(
+    async (id: string) => {
+      try {
+        await client.agentDeleteConversation(id);
+        if (conversationId === id) {
+          navigate("/me/chat");
+        }
+        setConversations((prev) => prev.filter((c) => c.id !== id));
+      } catch {
+        // Deletion failed.
+      }
+    },
+    [conversationId, navigate],
+  );
+
+  return (
+    <div className="flex flex-col">
+      {/* Header */}
+      <div className="mb-2 flex items-center justify-between px-0.5 py-1">
+        <div className="flex items-center gap-2">
+          <span className="text-xs font-semibold uppercase tracking-[0.06em] text-muted-foreground">
+            AI Chats
+          </span>
+        </div>
+        <motion.button
+          type="button"
+          whileHover={{ scale: 1.05 }}
+          whileTap={{ scale: 0.92 }}
+          className="inline-flex size-6 cursor-pointer items-center justify-center rounded-md bg-muted/60 text-muted-foreground/60 transition-colors hover:bg-primary/10 hover:text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          onClick={handleNewChat}
+          aria-label="New chat"
+        >
+          <Plus className="size-3" aria-hidden="true" />
+        </motion.button>
+      </div>
+
+      {/* Conversation list */}
+      {loading ? (
+        <div className="space-y-1">
+          {Array.from({ length: SKELETON_COUNT }).map((_, i) => (
+            <div className="h-9 rounded-lg px-2.5 py-2" key={i}>
+              <Shimmer duration={1.8} spread={1.5}>
+                {"\u00A0".repeat(24 + i * 6)}
+              </Shimmer>
+            </div>
+          ))}
+        </div>
+      ) : conversations.length === 0 ? (
+        <div className="flex flex-col items-center justify-center gap-2 py-8 text-center">
+          <div className="grid size-10 place-items-center rounded-xl bg-muted/30">
+            <Bot className="size-4 text-muted-foreground/25" />
+          </div>
+          <p className="text-[11px] text-muted-foreground/40">
+            Click + to start a chat
+          </p>
+        </div>
+      ) : (
+        <div className="space-y-0.5">
+          {conversations.map((conv) => {
+            const active = conversationId === conv.id;
+            const initials = (conv.title || "AI").slice(0, 2).toUpperCase();
+            return (
+              <div
+                role="button"
+                tabIndex={0}
+                key={conv.id}
+                aria-current={active ? "page" : undefined}
+                aria-label={conv.title || "Untitled chat"}
+                className={cn(
+                  "group relative flex w-full cursor-pointer items-center gap-2.5 rounded-lg px-2.5 py-2 text-left transition-all duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                  active
+                    ? "bg-primary/[0.08] text-foreground shadow-[inset_0_0_0_1px_var(--color-primary)/15]"
+                    : "text-muted-foreground hover:bg-accent/50 hover:text-foreground hover:shadow-sm",
+                )}
+                onClick={() => navigate(`/me/chat/${conv.id}`)}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter" || e.key === " ") {
+                    e.preventDefault();
+                    navigate(`/me/chat/${conv.id}`);
+                  }
+                }}
+              >
+                {active && (
+                  <span className="absolute left-0 top-1/2 h-5 w-[3px] -translate-y-1/2 rounded-r-full bg-primary/70" />
+                )}
+                <span
+                  className={cn(
+                    "grid size-7 shrink-0 place-items-center rounded-lg text-[10px] font-bold transition-colors",
+                    active
+                      ? "bg-primary/15 text-primary/70"
+                      : "bg-muted/60 text-muted-foreground/50 group-hover:bg-primary/10 group-hover:text-primary/60",
+                  )}
+                  aria-hidden="true"
+                >
+                  {initials}
+                </span>
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center justify-between gap-1.5">
+                    <span className="truncate text-[12px] font-medium leading-tight">
+                      {conv.title?.slice(0, 28) || "Untitled"}
+                    </span>
+                    <span className="shrink-0 text-[10px] tabular-nums text-muted-foreground/40">
+                      {formatTime(conv.last_message_at || conv.created_at)}
+                    </span>
+                  </div>
+                </div>
+                <button
+                  type="button"
+                  className="shrink-0 cursor-pointer rounded-md p-1 text-muted-foreground/30 opacity-0 transition-all duration-200 hover:bg-destructive/10 hover:text-destructive focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring group-hover:opacity-100"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    handleDelete(conv.id);
+                  }}
+                  aria-label={`Delete chat "${conv.title || "Untitled"}"`}
+                >
+                  <Trash2 className="size-3" aria-hidden="true" />
+                </button>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function PersonalSidebar() {
+  const { me } = useAuth();
+  const location = useLocation();
+  const showAgent = location.pathname.startsWith("/me/chat");
+
+  const personalItems = [
+    { label: "Overview", to: "/me", icon: <LayoutDashboard /> },
+    { label: "Repositories", to: "/me/repos", icon: <Folder /> },
+    { label: "Notifications", to: "/me/notifications", icon: <Bell />, badge: (me?.has_unread_notifications ?? 0) > 0 ? String(me?.has_unread_notifications ?? 0) : undefined },
+  ];
+
+  const socialItems = [
+    { label: "Stars", to: "/me/stars", icon: <Star /> },
+    { label: "Following", to: "/me/following", icon: <Users /> },
+  ];
+
+  return (
+    <aside className="flex h-full w-[248px] shrink-0 flex-col overflow-hidden bg-card">
+      <header className="flex h-14 shrink-0 items-center gap-3 border-b border-border px-4 shadow-sm">
+        <PersonalAvatar />
+        <button className="flex min-w-0 flex-1 items-center gap-2 text-left text-base font-semibold text-foreground">
+          <span className="truncate">{me?.display_name || me?.username || "User"}</span>
+          <ChevronDown className="size-4 shrink-0 text-muted-foreground" />
+        </button>
+        <Button className="size-8 text-muted-foreground" size="icon" variant="ghost">
+          <Search className="size-4" />
+        </Button>
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-3 py-4">
+        <div className="mb-4">
+          <PersonalModeSwitch />
+        </div>
+
+        {showAgent ? (
+          <section className="mb-5">
+            <AgentChatSidebar />
+          </section>
+        ) : (
+          <>
+            <section className="mb-5">
+              <button className="mb-2 flex w-full items-center justify-between px-2 text-xs font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+                Personal
+              </button>
+              <nav className="space-y-1">
+                {personalItems.map((item) => (
+                  <PersonalNavLink
+                    item={item}
+                    active={location.pathname === item.to}
+                    key={item.to}
+                  />
+                ))}
+              </nav>
+            </section>
+
+            <section className="mb-5">
+              <button className="mb-2 flex w-full items-center justify-between px-2 text-xs font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+                Social
+              </button>
+              <nav className="space-y-1">
+                {socialItems.map((item) => (
+                  <PersonalNavLink
+                    item={item}
+                    active={location.pathname === item.to}
+                    key={item.to}
+                  />
+                ))}
+              </nav>
+            </section>
+          </>
+        )}
+      </div>
+    </aside>
+  );
+}
+
+export function PersonalShell() {
+  return (
+    <NavShell>
+      <div className="flex h-full overflow-hidden">
+        <PersonalSidebar />
+        <main className="flex min-w-0 flex-1 flex-col overflow-hidden bg-background">
+          <div className="flex h-14 shrink-0 items-center border-b border-border px-6" />
+          <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">
+            <Outlet />
+          </div>
+        </main>
+      </div>
+    </NavShell>
+  );
+}
diff --git a/src/components/shell/rail.tsx b/src/components/shell/rail.tsx
new file mode 100644
index 0000000..ccf62cd
--- /dev/null
+++ b/src/components/shell/rail.tsx
@@ -0,0 +1,149 @@
+import { Link, useLocation } from "react-router";
+import { Home, Plus, Settings } from "lucide-react";
+import { useQuery } from "@tanstack/react-query";
+
+import { client, type WorkspaceResponse } from "@/client";
+import { CreateWorkspaceDialog } from "@/page/workspace/create";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "./shared";
+
+function WorkspaceIcon({
+  active,
+  workspace,
+}: {
+  active: boolean;
+  workspace: WorkspaceResponse;
+}) {
+  return (
+    <Link
+      aria-label={workspace.name}
+      className="group relative grid size-11 place-items-center"
+      title={workspace.name}
+      to={`/${workspace.name}/repos`}
+    >
+      <span
+        className={cn(
+          "absolute -left-3 h-2 w-1 rounded-r-full bg-foreground opacity-0 transition-all group-hover:h-5 group-hover:opacity-100",
+          active && "h-8 opacity-100",
+        )}
+      />
+      <span
+        className={cn(
+          "grid size-10 place-items-center overflow-hidden rounded-2xl bg-gradient-to-br text-sm font-semibold text-white shadow-sm ring-1 ring-black/5 transition-all group-hover:rounded-xl",
+          workspaceColor(workspace.name),
+          active && "rounded-xl ring-2 ring-primary/30",
+        )}
+      >
+        {workspace.avatar_url ? (
+          <img
+            alt=""
+            className="size-full object-cover"
+            src={workspace.avatar_url}
+          />
+        ) : (
+          workspaceInitial(workspace.name)
+        )}
+      </span>
+    </Link>
+  );
+}
+
+function RailButton({
+  label,
+  to,
+  children,
+}: {
+  label: string;
+  to: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Link
+      aria-label={label}
+      className="inline-flex size-10 shrink-0 items-center justify-center rounded-2xl border border-border bg-card text-muted-foreground shadow-sm transition-all hover:rounded-xl hover:bg-accent hover:text-primary"
+      title={label}
+      to={to}
+    >
+      {children}
+    </Link>
+  );
+}
+
+function WorkspaceSkeleton() {
+  return (
+    <div className="grid gap-3">
+      {Array.from({ length: 4 }).map((_, index) => (
+        <div
+          className="size-10 animate-pulse rounded-2xl bg-muted"
+          key={index}
+        />
+      ))}
+    </div>
+  );
+}
+
+export function WorkspaceRail() {
+  const location = useLocation();
+  const { data: workspaces = [], isLoading } = useQuery({
+    queryKey: ["workspace", "my"],
+    queryFn: async () => {
+      const response = await client.workspaceMyWorkspaces();
+      return response.data;
+    },
+    retry: false,
+  });
+
+  return (
+    <aside className="flex h-svh w-[72px] shrink-0 flex-col items-center bg-muted py-4">
+      <RailButton label="Home" to="/">
+        <Home className="size-5" />
+      </RailButton>
+
+      <div className="my-4 h-px w-8 bg-border" />
+
+      <nav
+        aria-label="Workspaces"
+        className="flex min-h-0 flex-1 flex-col items-center gap-3 overflow-y-auto overscroll-contain px-3"
+      >
+        {isLoading ? (
+          <WorkspaceSkeleton />
+        ) : (
+          workspaces.map((workspace) => (
+            <WorkspaceIcon
+              active={location.pathname.startsWith(`/${workspace.name}`)}
+              key={workspace.name}
+              workspace={workspace}
+            />
+          ))
+        )}
+
+        <CreateWorkspaceDialog>
+          <Button
+            aria-label="Create workspace"
+            className="size-10 rounded-2xl border-border bg-card text-muted-foreground shadow-sm transition-all hover:rounded-xl hover:bg-accent hover:text-primary"
+            size="icon"
+            variant="outline"
+          >
+            <Plus className="size-5" />
+          </Button>
+        </CreateWorkspaceDialog>
+      </nav>
+
+      <div className="mt-4">
+        <RailButton label="Settings" to="/settings">
+          <Settings className="size-5" />
+        </RailButton>
+      </div>
+    </aside>
+  );
+}
+
+export default function NavShell({ children }: { children?: React.ReactNode }) {
+  return (
+    <div className="flex h-svh overflow-hidden bg-background text-foreground">
+      <WorkspaceRail />
+      <div className="min-w-0 flex-1">{children}</div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/components/shell/settings-sidebar.tsx b/src/components/shell/settings-sidebar.tsx
new file mode 100644
index 0000000..c2a3dea
--- /dev/null
+++ b/src/components/shell/settings-sidebar.tsx
@@ -0,0 +1,152 @@
+import { Link, Outlet, useLocation } from "react-router";
+import {
+  Eye,
+  Key,
+  Lock,
+  Paintbrush,
+  PersonStanding,
+  Shield,
+  Terminal,
+  Bell,
+  ChevronDown,
+  Search,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import NavShell from "./rail";
+import { workspaceColor, workspaceInitial } from "./shared";
+import { useAuth } from "@/context/auth-context";
+import { Button } from "@/components/ui/button";
+
+function SettingsAvatar() {
+  const { me } = useAuth();
+  const name = me?.display_name || me?.username || "User";
+
+  return (
+    <span
+      className={cn(
+        "grid size-9 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-sm font-semibold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {me?.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={me.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+function SettingsNavLink({ item, active }: { item: { label: string; to: string; icon: React.ReactNode }; active: boolean }) {
+  return (
+    <Link
+      className={cn(
+        "flex h-9 items-center gap-2.5 rounded-lg px-3 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
+        active && "bg-accent text-foreground",
+      )}
+      to={item.to}
+    >
+      <span className="text-muted-foreground [&_svg]:size-4">{item.icon}</span>
+      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+    </Link>
+  );
+}
+
+function SettingsSidebar() {
+  const location = useLocation();
+
+  const accountItems = [
+    { label: "Profile", to: "/settings/profile", icon: <PersonStanding /> },
+    { label: "Security", to: "/settings/security", icon: <Lock /> },
+  ];
+
+  const preferenceItems = [
+    { label: "Appearance", to: "/settings/appearance", icon: <Paintbrush /> },
+    { label: "Notifications", to: "/settings/notifications", icon: <Bell /> },
+    { label: "Privacy", to: "/settings/privacy", icon: <Shield /> },
+    { label: "Accessibility", to: "/settings/accessibility", icon: <Eye /> },
+  ];
+
+  const developerItems = [
+    { label: "Access Tokens", to: "/settings/tokens", icon: <Key /> },
+    { label: "SSH Keys", to: "/settings/ssh-keys", icon: <Terminal /> },
+  ];
+
+  return (
+    <aside className="flex h-full w-[248px] shrink-0 flex-col overflow-hidden bg-card">
+      <header className="flex h-14 shrink-0 items-center gap-3 border-b border-border px-4 shadow-sm">
+        <SettingsAvatar />
+        <button className="flex min-w-0 flex-1 items-center gap-2 text-left text-base font-semibold text-foreground">
+          <span className="truncate">Settings</span>
+          <ChevronDown className="size-4 shrink-0 text-muted-foreground" />
+        </button>
+        <Button className="size-8 text-muted-foreground" size="icon" variant="ghost">
+          <Search className="size-4" />
+        </Button>
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-3 py-4">
+        <section className="mb-5">
+          <button className="mb-2 flex w-full items-center justify-between px-2 text-xs font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+            Account
+          </button>
+          <nav className="space-y-1">
+            {accountItems.map((item) => (
+              <SettingsNavLink
+                item={item}
+                active={location.pathname === item.to}
+                key={item.to}
+              />
+            ))}
+          </nav>
+        </section>
+
+        <section className="mb-5">
+          <button className="mb-2 flex w-full items-center justify-between px-2 text-xs font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+            Preferences
+          </button>
+          <nav className="space-y-1">
+            {preferenceItems.map((item) => (
+              <SettingsNavLink
+                item={item}
+                active={location.pathname === item.to}
+                key={item.to}
+              />
+            ))}
+          </nav>
+        </section>
+
+        <section className="mb-5">
+          <button className="mb-2 flex w-full items-center justify-between px-2 text-xs font-semibold uppercase tracking-[0.08em] text-muted-foreground">
+            Developer
+          </button>
+          <nav className="space-y-1">
+            {developerItems.map((item) => (
+              <SettingsNavLink
+                item={item}
+                active={location.pathname === item.to}
+                key={item.to}
+              />
+            ))}
+          </nav>
+        </section>
+      </div>
+    </aside>
+  );
+}
+
+export function SettingsShell() {
+  return (
+    <NavShell>
+      <div className="flex h-full overflow-hidden">
+        <SettingsSidebar />
+        <main className="flex min-w-0 flex-1 flex-col overflow-hidden bg-background">
+          <div className="flex h-14 shrink-0 items-center border-b border-border px-6" />
+          <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">
+            <Outlet />
+          </div>
+        </main>
+      </div>
+    </NavShell>
+  );
+}
\ No newline at end of file
diff --git a/src/components/shell/shared.tsx b/src/components/shell/shared.tsx
new file mode 100644
index 0000000..00d7556
--- /dev/null
+++ b/src/components/shell/shared.tsx
@@ -0,0 +1,49 @@
+import { Link, useLocation } from "react-router";
+import { cn } from "@/lib/utils";
+
+export type ShellNavItem = {
+  label: string;
+  to: string;
+  icon: React.ReactNode;
+  badge?: string;
+};
+
+export function ShellNavLink({ item }: { item: ShellNavItem }) {
+  const location = useLocation();
+  const active = location.pathname === item.to || location.pathname.startsWith(`${item.to}/`);
+
+  return (
+    <Link
+      className={cn(
+        "flex h-9 items-center gap-2.5 rounded-lg px-3 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
+        active && "bg-accent text-foreground",
+      )}
+      to={item.to}
+    >
+      <span className="text-muted-foreground [&_svg]:size-4">{item.icon}</span>
+      <span className="min-w-0 flex-1 truncate">{item.label}</span>
+      {item.badge && (
+        <span className="rounded-full bg-card px-2 py-0.5 text-xs text-muted-foreground">
+          {item.badge}
+        </span>
+      )}
+    </Link>
+  );
+}
+
+export function workspaceInitial(name: string) {
+  return name.trim().slice(0, 1).toUpperCase();
+}
+
+export function workspaceColor(name: string) {
+  const colors = [
+    "from-indigo-500 to-violet-500",
+    "from-sky-500 to-cyan-500",
+    "from-emerald-500 to-teal-500",
+    "from-amber-500 to-orange-500",
+    "from-rose-500 to-pink-500",
+    "from-slate-600 to-zinc-800",
+  ];
+  const index = Array.from(name).reduce((sum, char) => sum + char.charCodeAt(0), 0);
+  return colors[index % colors.length];
+}
\ No newline at end of file
diff --git a/src/components/shell/workspace-sidebar-inner.tsx b/src/components/shell/workspace-sidebar-inner.tsx
new file mode 100644
index 0000000..4e4002b
--- /dev/null
+++ b/src/components/shell/workspace-sidebar-inner.tsx
@@ -0,0 +1,73 @@
+import { Link, useLocation } from "react-router";
+import { Grid2X2, MessageSquare } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "./shared";
+import { type WorkspaceResponse } from "@/client";
+
+export function WorkspaceAvatar({ workspace }: { workspace?: WorkspaceResponse }) {
+  const name = workspace?.name ?? "Workspace";
+  return (
+    <span
+      className={cn(
+        "grid size-9 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-sm font-semibold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {workspace?.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={workspace.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+export function WorkspaceModeSwitch({ projectName }: { projectName: string }) {
+  const location = useLocation();
+  const modes = [
+    {
+      label: "Channel",
+      to: `/${projectName}/channel`,
+      icon: <MessageSquare className="size-4" />,
+      activePaths: [`/${projectName}/channel`, `/${projectName}/chat`],
+    },
+    {
+      label: "Workplan",
+      to: `/${projectName}/workplan/chat`,
+      icon: <Grid2X2 className="size-4" />,
+      activePaths: [
+        `/${projectName}/repos`,
+        `/${projectName}/issues`,
+        `/${projectName}/settings`,
+        `/${projectName}/workplan`,
+      ],
+    },
+  ];
+
+  return (
+    <nav
+      aria-label="Workspace mode"
+      className="grid grid-cols-2 gap-1 rounded-xl bg-muted/70 p-1"
+    >
+      {modes.map((mode) => {
+        const active = mode.activePaths.some(
+          (path) => location.pathname === path || location.pathname.startsWith(`${path}/`),
+        );
+
+        return (
+          <Link
+            className={cn(
+              "flex h-8 items-center justify-center gap-2 rounded-md text-sm font-semibold text-muted-foreground transition-colors hover:text-foreground",
+              active && "bg-card text-foreground shadow-sm ring-1 ring-border",
+            )}
+            key={mode.to}
+            to={mode.to}
+          >
+            {mode.icon}
+            <span className="truncate">{mode.label}</span>
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}
\ No newline at end of file
diff --git a/src/components/shell/workspace-sidebar.tsx b/src/components/shell/workspace-sidebar.tsx
new file mode 100644
index 0000000..0cd0734
--- /dev/null
+++ b/src/components/shell/workspace-sidebar.tsx
@@ -0,0 +1,618 @@
+import { useMemo, useState, createContext, useContext } from "react";
+import { Link, Outlet, useLocation, useParams } from "react-router";
+import {
+  Bell,
+  ChevronDown,
+  ChevronRight,
+  Folder,
+  GitPullRequest,
+  Hash,
+  Home,
+  Lock,
+  Plus,
+  Search,
+  Settings,
+  Users,
+  X,
+} from "lucide-react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+
+import { api, client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { CommandPalette } from "@/components/CommandPalette";
+import RoomCreateDialog from "@/page/workspace/channel/room-create-dialog";
+import NavShell from "./rail";
+import { ShellNavLink } from "./shared";
+import { cn } from "@/lib/utils";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { WorkspaceAvatar, WorkspaceModeSwitch } from "./workspace-sidebar-inner";
+import { WorkplanChatSidebar } from "@/page/workspace/workplan/chat-sidebar";
+
+/* ------------------------------------------------------------------ */
+/*  Panel context                                                      */
+/* ------------------------------------------------------------------ */
+
+type WorkspaceMember = {
+  id: string;
+  username: string;
+  display_name: string;
+  avatar_url: string;
+};
+
+type PanelContextValue = {
+  showMembers: boolean;
+  toggleMembers: () => void;
+  closeMembers: () => void;
+  showSearch: boolean;
+  toggleSearch: () => void;
+  closeSearch: () => void;
+  members: WorkspaceMember[];
+  membersLoading: boolean;
+};
+
+const PanelContext = createContext<PanelContextValue>({
+  showMembers: false,
+  toggleMembers: () => {},
+  closeMembers: () => {},
+  showSearch: false,
+  toggleSearch: () => {},
+  closeSearch: () => {},
+  members: [],
+  membersLoading: false,
+});
+
+export const usePanelContext = () => useContext(PanelContext);
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+type ChannelItem = {
+  id: string;
+  name: string;
+  topic?: string | null;
+  room_type: string;
+  is_private: boolean;
+  category?: string | null;
+  workspace_id: string;
+};
+
+type CategoryItem = {
+  id: string;
+  name: string;
+  position: number;
+};
+
+/* ------------------------------------------------------------------ */
+/*  Channel Link                                                       */
+/* ------------------------------------------------------------------ */
+
+function ChannelLink({
+  channel,
+  projectName,
+}: {
+  channel: ChannelItem;
+  projectName: string;
+}) {
+  const location = useLocation();
+  const to = `/${projectName}/channel/${channel.id}`;
+  const active = location.pathname === to;
+
+  return (
+    <Link
+      className={cn(
+        "flex h-[30px] items-center gap-2 rounded-md px-2 text-[13px] transition-all duration-150",
+        active
+          ? "bg-primary/[0.06] font-medium text-foreground"
+          : "text-muted-foreground/70 hover:bg-accent/[0.35] hover:text-foreground",
+      )}
+      to={to}
+    >
+      <span
+        className={cn(
+          "shrink-0 transition-colors duration-150",
+          active ? "text-primary/60" : "text-muted-foreground/40",
+        )}
+      >
+        <Hash className="size-[15px]" />
+      </span>
+      <span className="min-w-0 flex-1 truncate">{channel.name}</span>
+      {channel.is_private && (
+        <Lock className="size-3 shrink-0 text-muted-foreground/25" />
+      )}
+    </Link>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Channel Category Group                                             */
+/* ------------------------------------------------------------------ */
+
+function ChannelCategoryGroup({
+  name,
+  channels,
+  projectName,
+  defaultOpen,
+}: {
+  name: string;
+  channels: ChannelItem[];
+  projectName: string;
+  defaultOpen: boolean;
+}) {
+  const [open, setOpen] = useState(defaultOpen);
+
+  return (
+    <div className="mb-0.5">
+      <button
+        className="flex h-7 w-full items-center gap-1.5 rounded-md px-1.5 text-[11px] font-semibold uppercase tracking-[0.06em] text-muted-foreground/35 transition-colors hover:text-muted-foreground/65"
+        onClick={() => setOpen((v) => !v)}
+        type="button"
+      >
+        <ChevronRight
+          className={cn(
+            "size-3.5 shrink-0 transition-transform duration-200",
+            open && "rotate-90",
+          )}
+        />
+        <span className="flex-1 truncate text-left">{name}</span>
+        <span className="text-[10px] tabular-nums text-muted-foreground/25">
+          {channels.length}
+        </span>
+      </button>
+      <div
+        className={cn(
+          "grid transition-[grid-template-rows] duration-200",
+          open ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
+        )}
+      >
+        <div className="overflow-hidden">
+          <div className="space-y-[1px] py-0.5">
+            {channels.map((ch) => (
+              <ChannelLink channel={ch} key={ch.id} projectName={projectName} />
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  WorkspaceSidebar                                                   */
+/* ------------------------------------------------------------------ */
+
+function WorkspaceSidebar() {
+  const { projectName = "" } = useParams();
+  const location = useLocation();
+  const queryClient = useQueryClient();
+  const { data: currentWorkspace } = useQuery({
+    enabled: Boolean(projectName),
+    queryKey: ["workspace", projectName],
+    queryFn: async () => {
+      const response = await client.workspaceGetWorkspace(projectName);
+      return response.data;
+    },
+    retry: false,
+  });
+
+  const { data: channelsData } = useQuery<{
+    rooms: ChannelItem[];
+    categories: CategoryItem[];
+    workspace_id?: string;
+  }>({
+    queryKey: ["channel", "rooms"],
+    queryFn: async () => {
+      const response = await api.get("/api/v1/ws/rooms");
+      return response.data;
+    },
+    retry: false,
+  });
+  const channels = channelsData?.rooms ?? [];
+  const categories = channelsData?.categories ?? [];
+
+  // Group channels by category
+  const { categorized, uncategorized } = useMemo(() => {
+    const byCat = new Map<string | null, ChannelItem[]>();
+    for (const ch of channels) {
+      const key = ch.category ?? null;
+      if (!byCat.has(key)) byCat.set(key, []);
+      byCat.get(key)!.push(ch);
+    }
+
+    const catGroups: { id: string; name: string; channels: ChannelItem[] }[] = [];
+    const flat: ChannelItem[] = [];
+
+    if (categories.length > 0) {
+      const sorted = [...categories].sort((a, b) => a.position - b.position);
+      for (const cat of sorted) {
+        const catChannels = byCat.get(cat.id);
+        if (catChannels && catChannels.length > 0) {
+          catGroups.push({ id: cat.id, name: cat.name, channels: catChannels });
+          byCat.delete(cat.id);
+        }
+      }
+    }
+
+    for (const [, chs] of byCat) {
+      if (chs.length > 0) flat.push(...chs);
+    }
+
+    return { categorized: catGroups, uncategorized: flat };
+  }, [channels, categories]);
+
+  const workspaceId =
+    channels[0]?.workspace_id ?? channelsData?.workspace_id ?? "";
+  const refreshChannels = () =>
+    queryClient.invalidateQueries({ queryKey: ["channel", "rooms"] });
+
+  const showChannel =
+    location.pathname === `/${projectName}/channel` ||
+    location.pathname.startsWith(`/${projectName}/channel/`) ||
+    location.pathname === `/${projectName}/chat` ||
+    location.pathname.startsWith(`/${projectName}/chat/`);
+
+  return (
+    <aside className="flex h-full w-[252px] shrink-0 flex-col overflow-hidden border-r border-border/30 bg-card">
+      {/* Header */}
+      <header className="flex h-[52px] shrink-0 items-center gap-2.5 border-b border-border/40 px-4">
+        <WorkspaceAvatar workspace={currentWorkspace} />
+        <button className="flex min-w-0 flex-1 items-center gap-1.5 text-left">
+          <span className="truncate text-sm font-semibold text-foreground">
+            {currentWorkspace?.name ?? projectName}
+          </span>
+          <ChevronDown className="size-3.5 shrink-0 text-muted-foreground/40" />
+        </button>
+        <Button
+          className="size-7 text-muted-foreground/30 hover:bg-accent/50 hover:text-muted-foreground"
+          size="icon"
+          variant="ghost"
+        >
+          <Search className="size-[15px]" />
+        </Button>
+      </header>
+
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-2 py-3">
+        <div className="mb-5">
+          <WorkspaceModeSwitch projectName={projectName} />
+        </div>
+
+        {showChannel ? (
+          <section className="mb-5">
+            {/* Channel list header */}
+            <div className="mb-1 flex items-center justify-between px-1.5">
+              <span className="text-[11px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/35">
+                Channels
+              </span>
+            </div>
+
+            {/* Uncategorized channels */}
+            <div className="space-y-[1px] py-0.5">
+              {uncategorized.map((ch) => (
+                <ChannelLink channel={ch} key={ch.id} projectName={projectName} />
+              ))}
+            </div>
+
+            {/* Categorized channels */}
+            {categorized.map((group) => (
+              <ChannelCategoryGroup
+                channels={group.channels}
+                defaultOpen={true}
+                key={group.id}
+                name={group.name}
+                projectName={projectName}
+              />
+            ))}
+
+            {/* Add channel button */}
+            <RoomCreateDialog
+              categories={
+                categories as unknown as {
+                  id: string;
+                  name: string;
+                  position: number;
+                }[]
+              }
+              onCreated={refreshChannels}
+              workspaceId={workspaceId}
+            >
+              <div className="mt-1 flex h-[30px] w-full cursor-pointer items-center gap-2 rounded-md px-2 text-[13px] text-muted-foreground/40 transition-all duration-150 hover:bg-accent/[0.35] hover:text-muted-foreground/70">
+                <Plus className="size-[15px] shrink-0" />
+                <span>Add channel</span>
+              </div>
+            </RoomCreateDialog>
+          </section>
+        ) : (
+          <>
+            <section className="mb-5">
+              <button className="mb-2 flex w-full items-center justify-between px-2 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/35">
+                Workplan
+                <ChevronDown className="size-3.5" />
+              </button>
+              <nav className="space-y-[1px]">
+                <ShellNavLink
+                  item={{
+                    label: "Repository",
+                    to: `/${projectName}/repos`,
+                    icon: <Folder />,
+                  }}
+                />
+                <ShellNavLink
+                  item={{
+                    label: "Issues",
+                    to: `/${projectName}/issues`,
+                    icon: <GitPullRequest />,
+                  }}
+                />
+              </nav>
+            </section>
+            <section className="mb-5">
+              <WorkplanChatSidebar />
+            </section>
+          </>
+        )}
+      </div>
+
+      {/* Settings pinned at bottom (Workplan mode only) */}
+      {!showChannel && (
+        <div className="shrink-0 border-t border-border/30 px-3 py-2">
+          <ShellNavLink
+            item={{
+              label: "Settings",
+              to: `/${projectName}/settings`,
+              icon: <Settings />,
+            }}
+          />
+        </div>
+      )}
+    </aside>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  TopBar                                                             */
+/* ------------------------------------------------------------------ */
+
+function TopBar() {
+  const { projectName = "" } = useParams();
+  const location = useLocation();
+  const panel = usePanelContext();
+
+  const segments = location.pathname.split("/").filter(Boolean);
+  const isRepo = segments[1] === "repo" && segments.length >= 3;
+  const isChannel = segments[1] === "channel" && segments.length >= 3;
+  const roomId = isChannel ? segments[2] : null;
+
+  const { data: channelsData } = useQuery<{
+    rooms: ChannelItem[];
+    categories: CategoryItem[];
+  }>({
+    queryKey: ["channel", "rooms"],
+    queryFn: async () => {
+      const response = await api.get("/api/v1/ws/rooms");
+      return response.data;
+    },
+    retry: false,
+    enabled: isChannel,
+  });
+
+  const channelName = roomId
+    ? channelsData?.rooms?.find((r) => r.id === roomId)?.name
+    : null;
+
+  const title = isRepo
+    ? segments[2]
+    : isChannel
+      ? channelName
+        ? `#${channelName}`
+        : `#${segments[2]}`
+      : location.pathname.includes("/issues")
+        ? "Issues"
+        : location.pathname.includes("/settings")
+          ? "Settings"
+          : "Repos";
+
+  const repoName = isRepo ? segments[2] : null;
+
+  return (
+    <header className="flex h-[52px] shrink-0 items-center justify-between border-b border-border/40 bg-background/70 px-5 backdrop-blur-sm">
+      <div className="flex min-w-0 items-center gap-2 text-sm">
+        <Link
+          className="shrink-0 text-muted-foreground/50 transition-colors hover:text-foreground"
+          to="/"
+        >
+          <Home className="size-[18px]" />
+        </Link>
+        <span className="shrink-0 text-muted-foreground/20">/</span>
+        <Link
+          className="shrink-0 truncate text-muted-foreground/60 transition-colors hover:text-foreground"
+          to={`/${projectName}/repos`}
+        >
+          {projectName}
+        </Link>
+        {repoName && (
+          <>
+            <span className="shrink-0 text-muted-foreground/20">/</span>
+            <span className="shrink-0 truncate text-foreground/50">
+              {repoName}
+            </span>
+          </>
+        )}
+        <span className="shrink-0 text-muted-foreground/20">/</span>
+        <span className="shrink-0 font-semibold text-foreground">
+          {title}
+        </span>
+      </div>
+
+      <div className="flex items-center gap-0.5 text-muted-foreground/40">
+        <CommandPalette />
+        <button
+          className={cn(
+            "grid size-8 place-items-center rounded-lg transition-all duration-150 hover:bg-accent/50 hover:text-muted-foreground",
+            panel.showSearch && "bg-accent/50 text-foreground",
+          )}
+          onClick={panel.toggleSearch}
+          title="Search"
+        >
+          <Search className="size-[15px]" />
+        </button>
+        <button
+          className={cn(
+            "grid size-8 place-items-center rounded-lg transition-all duration-150 hover:bg-accent/50 hover:text-muted-foreground",
+            panel.showMembers && "bg-accent/50 text-foreground",
+          )}
+          onClick={panel.toggleMembers}
+          title="Members"
+        >
+          <Users className="size-[15px]" />
+        </button>
+        <button
+          className="grid size-8 place-items-center rounded-lg transition-all duration-150 hover:bg-accent/50 hover:text-muted-foreground"
+          title="Notifications"
+        >
+          <Bell className="size-[15px]" />
+        </button>
+      </div>
+    </header>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  MembersPanel                                                       */
+/* ------------------------------------------------------------------ */
+
+function MembersPanel() {
+  const panel = usePanelContext();
+
+  return (
+    <div
+      className={cn(
+        "absolute inset-y-0 right-0 z-40 w-72 border-l border-border/30 bg-card shadow-2xl transition-transform duration-300 ease-out",
+        panel.showMembers ? "translate-x-0" : "translate-x-full",
+      )}
+    >
+      <div className="flex h-full flex-col">
+        <div className="flex h-[52px] shrink-0 items-center justify-between border-b border-border/40 px-4">
+          <div className="flex items-center gap-2">
+            <Users className="size-4 text-primary/60" />
+            <span className="text-sm font-semibold text-foreground">
+              Members
+            </span>
+          </div>
+          <Button
+            className="size-7 text-muted-foreground/40 hover:bg-accent/50 hover:text-foreground"
+            onClick={panel.closeMembers}
+            size="icon"
+            variant="ghost"
+          >
+            <X className="size-4" />
+          </Button>
+        </div>
+        <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-3 py-2">
+          {panel.membersLoading && (
+            <div className="flex items-center gap-2 px-2 py-3">
+              <div className="size-4 animate-spin rounded-full border-2 border-muted-foreground/20 border-t-muted-foreground/50" />
+              <span className="text-xs text-muted-foreground/40">
+                Loading members…
+              </span>
+            </div>
+          )}
+          {!panel.membersLoading && panel.members.length === 0 && (
+            <p className="px-2 py-3 text-xs text-muted-foreground/35">
+              No members yet
+            </p>
+          )}
+          <div className="space-y-[1px]">
+            {panel.members.map((member) => (
+              <div
+                className="flex items-center gap-2.5 rounded-md px-2 py-1.5 transition-colors hover:bg-accent/[0.03]"
+                key={member.id}
+              >
+                <span className="grid size-8 place-items-center rounded-full bg-gradient-to-br from-muted-foreground/10 to-muted-foreground/5 text-xs font-semibold text-muted-foreground/60">
+                  {member.display_name?.[0]?.toUpperCase() ||
+                    member.username[0]?.toUpperCase()}
+                </span>
+                <span className="min-w-0 flex-1 truncate text-sm text-foreground">
+                  {member.display_name || member.username}
+                </span>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Shell                                                              */
+/* ------------------------------------------------------------------ */
+
+export function WorkspaceShell() {
+  const [showMembers, setShowMembers] = useState(false);
+  const [showSearch, setShowSearch] = useState(false);
+
+  const { data: channelsData } = useQuery<{
+    rooms: ChannelItem[];
+    categories: CategoryItem[];
+    workspace_id?: string;
+  }>({
+    queryKey: ["channel", "rooms"],
+    queryFn: async () => {
+      const response = await api.get("/api/v1/ws/rooms");
+      return response.data;
+    },
+    retry: false,
+  });
+  const workspaceId =
+    channelsData?.rooms[0]?.workspace_id ??
+    channelsData?.workspace_id ??
+    "";
+
+  const { data: members = [], isLoading: membersLoading } = useQuery<
+    WorkspaceMember[]
+  >({
+    queryKey: ["workspace", "members", workspaceId],
+    queryFn: async () => {
+      const res = await api.get<WorkspaceMember[]>(
+        `/api/v1/ws/workspaces/${workspaceId}/members`,
+      );
+      return res.data;
+    },
+    enabled: Boolean(workspaceId),
+    retry: false,
+    staleTime: 30000,
+  });
+
+  const panelCtx = useMemo<PanelContextValue>(
+    () => ({
+      showMembers,
+      toggleMembers: () => setShowMembers((v) => !v),
+      closeMembers: () => setShowMembers(false),
+      showSearch,
+      toggleSearch: () => setShowSearch((v) => !v),
+      closeSearch: () => setShowSearch(false),
+      members,
+      membersLoading,
+    }),
+    [showMembers, showSearch, members, membersLoading],
+  );
+
+  return (
+    <NavShell>
+      <TooltipProvider delay={300}>
+        <PanelContext.Provider value={panelCtx}>
+          <div className="relative flex h-full min-w-0 overflow-hidden">
+            <WorkspaceSidebar />
+            <main className="flex min-w-0 flex-1 flex-col overflow-hidden bg-background">
+              <TopBar />
+              <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">
+                <Outlet />
+              </div>
+            </main>
+            <MembersPanel />
+          </div>
+        </PanelContext.Provider>
+      </TooltipProvider>
+    </NavShell>
+  );
+}
diff --git a/src/components/ui/avatar-uploader.tsx b/src/components/ui/avatar-uploader.tsx
new file mode 100644
index 0000000..54b61d4
--- /dev/null
+++ b/src/components/ui/avatar-uploader.tsx
@@ -0,0 +1,189 @@
+import { useCallback, useRef, useState } from "react";
+import { Camera, Loader2, X } from "lucide-react";
+import { api } from "@/client";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+const MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+const ALLOWED_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+
+type Props = {
+  /** Current avatar URL to display as preview. */
+  currentUrl?: string | null;
+  /** Called with the returned avatar_url after successful upload. */
+  onUploaded: (url: string) => void;
+  /** The upload endpoint path (e.g. "/api/v1/user/avatar" or "/api/v1/workspace/my-workspace/avatar"). */
+  uploadEndpoint: string;
+  /** Accessible label for the component. */
+  label?: string;
+  /** Size of the avatar preview in Tailwind units (default h-24 w-24). */
+  size?: string;
+};
+
+export default function AvatarUploader({
+  currentUrl,
+  onUploaded,
+  uploadEndpoint,
+  label = "Avatar",
+  size = "size-24",
+}: Props) {
+  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState("");
+  const [isDragging, setIsDragging] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const displayUrl = previewUrl ?? currentUrl ?? undefined;
+
+  const upload = useCallback(
+    async (file: File) => {
+      if (!ALLOWED_TYPES.includes(file.type)) {
+        setError("Only PNG, JPEG, WebP, and GIF images are allowed.");
+        return;
+      }
+      if (file.size > MAX_SIZE) {
+        setError("Image must be under 5 MB.");
+        return;
+      }
+
+      setError("");
+      setUploading(true);
+
+      try {
+        // Show local preview immediately
+        const localPreview = URL.createObjectURL(file);
+        setPreviewUrl(localPreview);
+
+        // Read file as ArrayBuffer and upload as raw binary
+        const buffer = await file.arrayBuffer();
+        const res = await api.post<{ avatar_url: string }>(
+          uploadEndpoint,
+          buffer,
+          {
+            headers: { "Content-Type": file.type },
+          },
+        );
+
+        const url = res.data?.avatar_url;
+        if (url) {
+          onUploaded(url);
+        }
+      } catch (err) {
+        setError(
+          err instanceof Error ? err.message : "Failed to upload avatar.",
+        );
+        setPreviewUrl(null);
+      } finally {
+        setUploading(false);
+      }
+    },
+    [uploadEndpoint, onUploaded],
+  );
+
+  const handleFileChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const file = e.target.files?.[0];
+      if (file) upload(file);
+      // Reset so the same file can be selected again
+      if (inputRef.current) inputRef.current.value = "";
+    },
+    [upload],
+  );
+
+  const handleDrop = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault();
+      setIsDragging(false);
+      const file = e.dataTransfer.files?.[0];
+      if (file) upload(file);
+    },
+    [upload],
+  );
+
+  const handleDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    setIsDragging(true);
+  }, []);
+
+  const handleDragLeave = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    setIsDragging(false);
+  }, []);
+
+  const handleRemove = useCallback(() => {
+    setPreviewUrl(null);
+    // Revoke local preview URL to avoid memory leak
+    if (previewUrl) URL.revokeObjectURL(previewUrl);
+  }, [previewUrl]);
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-4">
+        {/* Avatar preview / drop zone */}
+        <button
+          aria-label={`Upload ${label}`}
+          className={cn(
+            "relative flex shrink-0 cursor-pointer items-center justify-center overflow-hidden rounded-full border-2 transition-all duration-200",
+            size,
+            isDragging
+              ? "border-primary bg-primary/10 scale-105"
+              : "border-border/60 bg-muted/30 hover:border-primary/50 hover:bg-accent/40",
+          )}
+          onClick={() => inputRef.current?.click()}
+          onDragLeave={handleDragLeave}
+          onDragOver={handleDragOver}
+          onDrop={handleDrop}
+          type="button"
+        >
+          {displayUrl ? (
+            <img
+              alt={label}
+              className="size-full rounded-full object-cover"
+              src={displayUrl}
+            />
+          ) : (
+            <Camera className="size-6 text-muted-foreground/40" />
+          )}
+
+          {uploading && (
+            <div className="absolute inset-0 flex items-center justify-center rounded-full bg-background/60 backdrop-blur-[1px]">
+              <Loader2 className="size-6 animate-spin text-primary" />
+            </div>
+          )}
+        </button>
+
+        <div className="space-y-1.5">
+          <p className="text-sm font-medium text-foreground">{label}</p>
+          <p className="text-xs text-muted-foreground/70">
+            Click or drag to upload. PNG, JPEG, WebP, GIF up to 5 MB.
+          </p>
+          {error && (
+            <p className="text-xs text-destructive">{error}</p>
+          )}
+        </div>
+      </div>
+
+      {/* Hidden file input */}
+      <input
+        accept={ALLOWED_TYPES.join(",")}
+        className="hidden"
+        onChange={handleFileChange}
+        ref={inputRef}
+        type="file"
+      />
+
+      {/* Remove button when preview is local */}
+      {previewUrl && !uploading && (
+        <Button
+          className="h-7 cursor-pointer text-xs"
+          onClick={handleRemove}
+          size="sm"
+          variant="outline"
+        >
+          <X className="mr-1 size-3" />
+          Remove new photo
+        </Button>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/ui/demo/social.ts b/src/components/ui/demo/social.ts
new file mode 100644
index 0000000..4c4906d
--- /dev/null
+++ b/src/components/ui/demo/social.ts
@@ -0,0 +1,48 @@
+export const demoXPost = {
+  author: 'Manifest',
+  username: 'manifest_ui',
+  avatar: 'M',
+  verified: true,
+  content: 'Just shipped a new batch of agentic UI components. Build conversational interfaces faster than ever.',
+  time: '2h',
+  likes: '1.2K',
+  retweets: '234',
+  replies: '56',
+  views: '45.2K',
+}
+
+export const demoInstagramPost = {
+  author: 'manifest.ui',
+  avatar: 'M',
+  verified: true,
+  image:
+    'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800',
+  caption: 'Building the future of agentic UIs, one component at a time.',
+  likes: '2,847',
+  time: '2h',
+}
+
+export const demoLinkedInPost = {
+  author: 'Manifest',
+  headline: 'Manifest UI | Open Source',
+  avatar: 'M',
+  content: 'Excited to announce our latest milestone! We\'ve just crossed 10,000 developers using Manifest to build agentic UIs.',
+  time: '1d',
+  reactions: '1,234',
+  topReactions: ['like', 'celebrate', 'love'] as ('like' | 'celebrate' | 'support' | 'love' | 'insightful' | 'funny')[],
+  comments: '56',
+  reposts: '12',
+  postUrl: 'https://linkedin.com/posts/manifest-123',
+  repostUrl: 'https://linkedin.com/shareArticle?url=...',
+}
+
+export const demoYouTubePost = {
+  channel: 'Manifest',
+  avatar: 'M',
+  title: 'Building Agentic UIs with Manifest',
+  views: '12K',
+  time: '3 days ago',
+  thumbnail:
+    'https://images.unsplash.com/photo-1677442136019-21780ecad995?w=800',
+  duration: '15:42',
+}
diff --git a/src/components/ui/instagram-post.tsx b/src/components/ui/instagram-post.tsx
new file mode 100644
index 0000000..75c7593
--- /dev/null
+++ b/src/components/ui/instagram-post.tsx
@@ -0,0 +1,163 @@
+"use client"
+
+import { Heart, MessageCircle, Send, Bookmark, MoreHorizontal, Flag, UserMinus, Link, Code } from "lucide-react"
+import { demoInstagramPost } from './demo/social'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * InstagramPostProps
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Props for the InstagramPost component, which displays an Instagram-style
+ * post with image, caption, and engagement actions.
+ */
+export interface InstagramPostProps {
+  data?: {
+    /** Author's Instagram username. */
+    author?: string
+    /** Avatar letter fallback or image URL for the profile picture. */
+    avatar?: string
+    /** URL of the post image to display. */
+    image?: string
+    /** Formatted like count (e.g., "2,847"). */
+    likes?: string
+    /** Post caption text content. */
+    caption?: string
+    /** Time since posted (e.g., "2 hours ago"). */
+    time?: string
+    /** Whether the author has a verified badge. */
+    verified?: boolean
+  }
+}
+
+/**
+ * An Instagram post embed component with image, caption, and engagement.
+ * Displays the post with like, comment, share, and save actions.
+ *
+ * Features:
+ * - Square aspect ratio image display
+ * - Gradient avatar ring for stories indicator
+ * - Verified badge support
+ * - Action buttons (like, comment, share, save)
+ * - Dropdown menu (report, unfollow, copy link, embed)
+ * - Like count and caption display
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <InstagramPost
+ *   data={{
+ *     author: "manifest.ai",
+ *     avatar: "M",
+ *     image: "https://example.com/photo.jpg",
+ *     likes: "2,847",
+ *     caption: "Check out this amazing view!",
+ *     time: "2 hours ago",
+ *     verified: true
+ *   }}
+ * />
+ * ```
+ */
+export function InstagramPost({ data }: InstagramPostProps) {
+  const resolved: NonNullable<InstagramPostProps['data']> = data ?? demoInstagramPost
+  const author = resolved?.author
+  const avatar = resolved?.avatar
+  const image = resolved?.image
+  const likes = resolved?.likes
+  const caption = resolved?.caption
+  const time = resolved?.time
+  const verified = resolved?.verified
+
+  if (!author && !image && !caption) {
+    return null
+  }
+
+  return (
+    <div className="rounded-xl border bg-card overflow-hidden">
+      {(author || avatar) && (
+        <div className="flex items-center justify-between p-3">
+          <div className="flex items-center gap-2">
+            {avatar && (
+              <div className="h-8 w-8 rounded-full bg-gradient-to-br from-[#833AB4] via-[#FD1D1D] to-[#F77737] p-0.5">
+                <div className="h-full w-full rounded-full bg-card flex items-center justify-center text-xs font-semibold">
+                  {avatar}
+                </div>
+              </div>
+            )}
+            <div className="flex items-center gap-1">
+              {author && <span className="font-semibold text-sm">{author}</span>}
+              {verified && (
+                <svg className="h-3.5 w-3.5 text-blue-500" viewBox="0 0 24 24" fill="currentColor">
+                  <path d="M22.5 12.5c0-1.58-.875-2.95-2.148-3.6.154-.435.238-.905.238-1.4 0-2.21-1.71-3.998-3.818-3.998-.47 0-.92.084-1.336.25C14.818 2.415 13.51 1.5 12 1.5s-2.816.917-3.437 2.25c-.415-.165-.866-.25-1.336-.25-2.11 0-3.818 1.79-3.818 4 0 .494.083.964.237 1.4-1.272.65-2.147 2.018-2.147 3.6 0 1.495.782 2.798 1.942 3.486-.02.17-.032.34-.032.514 0 2.21 1.708 4 3.818 4 .47 0 .92-.086 1.335-.25.62 1.334 1.926 2.25 3.437 2.25 1.512 0 2.818-.916 3.437-2.25.415.163.865.248 1.336.248 2.11 0 3.818-1.79 3.818-4 0-.174-.012-.344-.033-.513 1.158-.687 1.943-1.99 1.943-3.484z" />
+                </svg>
+              )}
+            </div>
+          </div>
+          <DropdownMenu>
+            <DropdownMenuTrigger render={<button className="text-foreground hover:text-muted-foreground transition-colors cursor-pointer" />}><MoreHorizontal className="h-5 w-5" /></DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuItem>
+                <Flag className="mr-2 h-4 w-4" />
+                Report
+              </DropdownMenuItem>
+              <DropdownMenuItem>
+                <UserMinus className="mr-2 h-4 w-4" />
+                Unfollow
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem>
+                <Link className="mr-2 h-4 w-4" />
+                Copy link
+              </DropdownMenuItem>
+              <DropdownMenuItem>
+                <Code className="mr-2 h-4 w-4" />
+                Embed
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+      )}
+      {image && (
+        <div className="aspect-square bg-muted">
+          <img src={image} alt={author ? `Instagram post by ${author}` : 'Instagram post'} className="w-full h-full object-cover" />
+        </div>
+      )}
+      {(likes || caption || time) && (
+        <div className="p-3 space-y-2">
+          <div className="flex items-center justify-between">
+            <div className="flex items-center gap-4">
+              <button aria-label="Like" className="hover:text-muted-foreground transition-colors cursor-pointer">
+                <Heart className="h-6 w-6" />
+              </button>
+              <button aria-label="Comment" className="hover:text-muted-foreground transition-colors cursor-pointer">
+                <MessageCircle className="h-6 w-6" />
+              </button>
+              <button aria-label="Share" className="hover:text-muted-foreground transition-colors cursor-pointer">
+                <Send className="h-6 w-6" />
+              </button>
+            </div>
+            <button aria-label="Save" className="hover:text-muted-foreground transition-colors cursor-pointer">
+              <Bookmark className="h-6 w-6" />
+            </button>
+          </div>
+          {likes && <p className="font-semibold text-sm">{likes} likes</p>}
+          {(author || caption) && (
+            <p className="text-sm">
+              {author && <span className="font-semibold">{author}</span>}
+              {author && caption && " "}
+              {caption}
+            </p>
+          )}
+          {time && <p className="text-xs text-muted-foreground">{time}</p>}
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/src/components/ui/linkedin-post.tsx b/src/components/ui/linkedin-post.tsx
new file mode 100644
index 0000000..41123a1
--- /dev/null
+++ b/src/components/ui/linkedin-post.tsx
@@ -0,0 +1,483 @@
+'use client';
+
+import { Repeat2 } from 'lucide-react';
+import type { JSX } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
+import { demoLinkedInPost } from './demo/social';
+
+/** Reaction type for LinkedIn posts */
+type ReactionType = 'like' | 'celebrate' | 'support' | 'love' | 'insightful' | 'funny';
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * LinkedInPostProps
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Props for the LinkedInPost component, which displays a LinkedIn-style
+ * post with professional author info.
+ */
+export interface LinkedInPostProps {
+  data?: {
+    /** Author's display name. */
+    author?: string;
+    /** Author's professional headline or title. */
+    headline?: string;
+    /** Avatar letter fallback or image URL for the profile picture. */
+    avatar?: string;
+    /** Post text content (supports line breaks and hashtags). */
+    content?: string;
+    /** Time since posted (e.g., "2h"). */
+    time?: string;
+    /** Optional image URL for the post. */
+    image?: string;
+    /** Number of reactions (e.g., "1,234" or "1.2K"). */
+    reactions?: string;
+    /** Top reaction types to display (max 3 icons shown). */
+    topReactions?: ReactionType[];
+    /** Number of comments (e.g., "56"). */
+    comments?: string;
+    /** Number of reposts (e.g., "12"). */
+    reposts?: string;
+    /** URL to the original LinkedIn post. If provided, shows the LinkedIn icon. */
+    postUrl?: string;
+    /** URL for the repost action. If provided, shows the repost button in footer. */
+    repostUrl?: string;
+  };
+  appearance?: {
+    /** Maximum number of lines to show before truncating. @default 3 */
+    maxLines?: number;
+  };
+}
+
+/** Parses content and styles hashtags and links */
+function formatContent(content: string): React.ReactNode[] {
+  // Regex to match hashtags and URLs
+  const pattern = /(#\w+)|(https?:\/\/[^\s]+)/g;
+  const parts: React.ReactNode[] = [];
+  let lastIndex = 0;
+  let match;
+
+  while ((match = pattern.exec(content)) !== null) {
+    // Add text before the match
+    if (match.index > lastIndex) {
+      parts.push(content.slice(lastIndex, match.index));
+    }
+
+    const hashtag = match[1];
+    const url = match[2];
+
+    if (hashtag) {
+      // Style hashtag
+      parts.push(
+        <span key={match.index} className="font-semibold" style={{ color: '#0a66c2' }}>
+          {hashtag}
+        </span>
+      );
+    } else if (url) {
+      // Style link
+      parts.push(
+        <a
+          key={match.index}
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="font-semibold hover:underline"
+          style={{ color: '#0a66c2' }}
+        >
+          {url}
+        </a>
+      );
+    }
+
+    lastIndex = pattern.lastIndex;
+  }
+
+  // Add remaining text
+  if (lastIndex < content.length) {
+    parts.push(content.slice(lastIndex));
+  }
+
+  return parts;
+}
+
+/** LinkedIn logo icon component */
+function LinkedInIcon({ className }: { className?: string }) {
+  return (
+    <svg viewBox="0 0 24 24" className={className} fill="currentColor">
+      <path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z" />
+    </svg>
+  );
+}
+
+/** Reaction icon components - Official LinkedIn reaction SVGs */
+const reactionIcons: Record<ReactionType, JSX.Element> = {
+  like: (
+    <svg viewBox="0 0 48 48" className="h-5 w-5">
+      <circle cx="24" cy="24" r="22" fill="#378fe9" />
+      <path
+        d="M25.22 19.08H11.76A2.7 2.7 0 009 22a2.85 2.85 0 002.91 2.67h.5A2.43 2.43 0 0010 27.18a2.52 2.52 0 002.31 2.5 2.51 2.51 0 001.05 4.45 2.54 2.54 0 00-.19 1.87 2.69 2.69 0 002.66 2H23a11.51 11.51 0 002.8-.37l4.52-1.32c.27-.08 4.19 0 6 0 3.15-.12 4-14.57 0-14.57 0 0-1.45.05-1.73 0s-.46-.6-1.25-1.45l-.07-.09c-1.15-1.24-2.45-2.85-3.37-3.75-2.24-2.19-4.08-4.07-5.38-6.92-.73-1.62-.81-2.35-2.35-2.35a2.45 2.45 0 00-2.1 2.56 23.77 23.77 0 00.32 2.52 23.64 23.64 0 003.1 6.92"
+        fill="#d0e8ff"
+        fillRule="evenodd"
+      />
+      <path
+        d="M25.22 19.08H11.76a2.76 2.76 0 00-2.76 3 2.84 2.84 0 002.92 2.64h.5a2.43 2.43 0 00-2.37 2.51 2.52 2.52 0 002.31 2.5h0a2.51 2.51 0 001.05 4.45 2.51 2.51 0 00-.24 1.82 2.69 2.69 0 002.66 2H23a12.08 12.08 0 002.8-.36l4.52-1.32c.27-.08 4.19 0 6 0 3.15-.12 4-14.57 0-14.57h-1.73c-.28 0-.46-.59-1.25-1.44l-.07-.09c-1.15-1.25-2.45-2.85-3.37-3.76-2.24-2.18-4.08-4.06-5.38-6.92-.73-1.61-.81-2.41-2.35-2.34a2.32 2.32 0 00-1.58.8 2.35 2.35 0 00-.52 1.71 23.45 23.45 0 00.32 2.52 23.32 23.32 0 003.1 6.89"
+        fill="none"
+        stroke="#004182"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+    </svg>
+  ),
+  celebrate: (
+    <svg viewBox="0 0 48 48" className="h-5 w-5">
+      <circle cx="24" cy="24" r="22" fill="#6dae4f" />
+      <path
+        d="M45.57 31l-1.42-1.07s-.59-5.63-1.61-6.71a18.45 18.45 0 01-3.81-7.49c-.49-1.67-.83-2.26-2.33-2.29a2.29 2.29 0 00-2 2.52 17.11 17.11 0 00.21 2.25c.55 2.92 1.15 5.31 1.23 5.45L22.3 13.53c-1-.77-2.49-1.11-3.49.22s-.19 2.55.83 3.32l7.07 5.32L28.83 24l-11.32-8.53c-1-.77-2.49-1.11-3.48.22s-.2 2.55.82 3.32l7.07 5.32 4.25 3.19L17 20.6c-1-.76-2.48-1.11-3.48.22s-.19 2.56.82 3.32l7.08 5.33L25 32.13l-7.1-5.33c-1-.76-2.46-1.14-3.42.13a2.37 2.37 0 00.76 3.41l12.67 9.47c2.24 1.67 6.26 1.89 6.2 1.89a19.63 19.63 0 002.44 1.3 10.12 10.12 0 006.36-4 15 15 0 002.66-8z"
+        fill="#ddf6d1"
+        fillRule="evenodd"
+      />
+      <path
+        d="M15.57 5.44l.7 3.12M25.49 9.25l-2.6 1.85M21.48 4.87l-1.9 5"
+        fill="none"
+        stroke="#165209"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+      <path
+        d="M45.42 31A7 7 0 0144 28.61c-.16-.67-.2-1.36-.33-2-.19-1-.36-2.59-1.12-3.4a18.45 18.45 0 01-3.81-7.49c-.49-1.67-.83-2.26-2.33-2.29a2.29 2.29 0 00-2 2.52 17.11 17.11 0 00.21 2.25c.55 2.92 1.15 5.31 1.23 5.45L22.3 13.53c-1-.77-2.49-1.11-3.49.22s-.19 2.55.83 3.32l7.07 5.32L28.83 24l-11.32-8.53c-1-.77-2.49-1.11-3.48.22s-.2 2.55.82 3.32l7.07 5.32 4.25 3.19L17 20.6c-1-.76-2.48-1.11-3.48.22s-.19 2.56.82 3.32l7.08 5.33L25 32.13l-7.1-5.33c-1-.76-2.46-1.14-3.42.13a2.37 2.37 0 00.76 3.41l12.67 9.47a8.29 8.29 0 003.55 1.56c.57.1 1.17.16 1.83.28a9.08 9.08 0 012.73.92 2.6 2.6 0 001.9.15 11.78 11.78 0 005.55-4.06 11.28 11.28 0 002.19-6.25 2.61 2.61 0 00-.24-1.41zM37.07 24.58L34.94 23"
+        fill="none"
+        stroke="#165209"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+    </svg>
+  ),
+  support: (
+    <svg viewBox="0 0 48 48" className="h-5 w-5">
+      <circle cx="24" cy="24" r="22" fill="#bba9d1" />
+      <path
+        d="M42.46 40.81a68.7 68.7 0 01-10.61-1h-.19a60.42 60.42 0 01-7.87-1.64c-2.29-.69-4.54-1.58-6.73-2.44l-1-.38c-2.09-.81-3.75-1.49-5.29-2.14l-.58-.24a21.88 21.88 0 01-2.68-1.27C6.34 31 6 30.06 6.49 29v-.09a1.77 1.77 0 011.74-1h.13a4.69 4.69 0 01.53 0c1.9.21 7.41 2.3 8.5 2.72l3.55.12H21l8 .28c-.62-.57-2.2-1.57-6-2.57-.73-.18-1.4-.39-1.56-.93a2.16 2.16 0 01.7-2.26 2.86 2.86 0 011.69-.39 8.72 8.72 0 012.09.25c.4.1.74.21 1 .31a12.13 12.13 0 002.59.58 27 27 0 014.29.98c4.48 1.2 5.35 3.45 5.92 4.81-.18-.56 0-.15.08-.36l.13-.17h.69c.77 0 2.23-.08 2.25-.08.37 0 2.1-.43 2.1-.08a18.84 18.84 0 01-2 9.41.61.61 0 01-.43.3z"
+        fill="#eae2f3"
+      />
+      <path
+        d="M17.81 10.09a4.52 4.52 0 00-6.4-.08l-.07.08a4.7 4.7 0 000 6.58l7 7.07 7-7.08a4.71 4.71 0 000-6.57 4.5 4.5 0 00-6.46 0l-.52.52z"
+        fill="#ecaa96"
+        fillRule="evenodd"
+      />
+      <path
+        d="M45.79 31.2c.32.23.33 2.66-.37 4.79a10.73 10.73 0 01-3.05 4.16c-.37.34-13.21-1.15-16.29-1.66S8 31.29 7.37 31s-.63-2.65 1-3.13 5.93 2.1 8.59 2.33 8.78.47 11 .47-2-1.51-3.11-1.91S22 28 21.64 26.9s.83-1.9 1.82-1.9a29.24 29.24 0 015.31 1.26 18.66 18.66 0 017 1.13A8.06 8.06 0 0140 31.2c.32.61 5.46-.2 5.79 0z"
+        fill="none"
+        stroke="#493d57"
+        strokeWidth="2"
+      />
+      <path
+        d="M9.2 27.44c-.66-1.93.42-2.94 1.64-2.94s2.5 1.22 4.54 2.59A48.66 48.66 0 0022 30.5"
+        fill="none"
+        stroke="#493d57"
+        strokeWidth="2"
+      />
+      <path
+        d="M17.92 9.45a5 5 0 00-7 7L18.47 24l7.59-7.55a4.93 4.93 0 001.37-4.32 5 5 0 00-2.71-3.63 4.81 4.81 0 00-2.18-.5 4.93 4.93 0 00-3.49 1.47l-.58.54z"
+        fill="none"
+        stroke="#77280c"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+    </svg>
+  ),
+  love: (
+    <svg viewBox="0 0 48 48" className="h-5 w-5">
+      <circle cx="24" cy="24" r="22" fill="#df704d" />
+      <path
+        d="M23.08 14.6a8.21 8.21 0 00-11.66 0 8.35 8.35 0 000 11.76L24 39l12.58-12.64a8.35 8.35 0 000-11.75 8.13 8.13 0 00-11.63 0l-.94.9z"
+        fill="#fff3f0"
+        stroke="#77280c"
+        fillRule="evenodd"
+      />
+      <path
+        d="M23.08 14.44a8.18 8.18 0 00-11.66 0 8.35 8.35 0 000 11.76L24 38.83 36.58 26.2a8.37 8.37 0 000-11.76 8.11 8.11 0 00-11.62 0l-.94.9z"
+        fill="none"
+        stroke="#77280c"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+      <path
+        d="M23 15.71a9.93 9.93 0 01.84 1.2 1 1 0 001.72-1 13 13 0 00-1.15-1.6 1 1 0 00-1.76.39 1 1 0 00.35 1.01z"
+        fill="#77280c"
+        fillRule="evenodd"
+      />
+    </svg>
+  ),
+  insightful: (
+    <svg viewBox="0 0 48 48" className="h-5 w-5">
+      <circle cx="24" cy="24" r="22" fill="#f5bb5c" />
+      <path
+        d="M26.58 41h-5a1.68 1.68 0 01-1.68-1.68v-4.2h8.4v4.2A1.69 1.69 0 0126.58 41z"
+        fill="#ffe1b2"
+        fillRule="evenodd"
+      />
+      <path
+        d="M19.87 35.92v-.84a10 10 0 00-.48-3.08 10.08 10.08 0 00-1.62-2.51 10.23 10.23 0 01-3.77-7.8v-.05a10.08 10.08 0 1120.16 0 10.55 10.55 0 01-4 8l-.13.11a3.75 3.75 0 00-.57.62 5.43 5.43 0 00-.72 1.47 10.05 10.05 0 00-.47 3.22v.84"
+        fill="#fcf0de"
+        fillRule="evenodd"
+      />
+      <path
+        d="M14 7.36l2.12 2.77M35 7.36l-2.12 2.77M24.06 4v4.2"
+        fill="none"
+        stroke="#5d3b01"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+      <path
+        d="M22.3 13.86a7 7 0 00-3.84 2.08 7.85 7.85 0 00-2.14 3.8"
+        fill="none"
+        stroke="#fff"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="3"
+      />
+      <path
+        d="M26.58 41h-5a1.68 1.68 0 01-1.68-1.68v-4.2h8.4v4.2A1.69 1.69 0 0126.58 41z"
+        fill="none"
+        stroke="#5d3b01"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+      <path
+        d="M19.86 35.92v-.84a10 10 0 00-.48-3.08 5.7 5.7 0 00-.82-1.49 8.06 8.06 0 00-1.16-1.31 11.05 11.05 0 01-1.17-1.2A10.53 10.53 0 0114 21.66v-.05a10.08 10.08 0 1117.88 6.28 12.25 12.25 0 01-1.79 1.81 3.54 3.54 0 00-.62.66 5.74 5.74 0 00-.72 1.47 10.34 10.34 0 00-.47 3.22v.84"
+        fill="none"
+        stroke="#5d3b01"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        strokeWidth="2"
+      />
+    </svg>
+  ),
+  funny: (
+    <svg viewBox="0 0 48 48" className="h-5 w-5">
+      <circle cx="24" cy="24" r="22" fill="#44bfd3" />
+      <circle cx="24" cy="24" r="16" fill="#d5f9fe" stroke="#104e58" strokeWidth="1.8" />
+      <path
+        d="M14.67,21.01l-.19,.3,.68,.7,.42-.26c1.82-1.12,4.02-1.45,6.08-.9l.46-.86c-2.28-1.99-5.79-1.5-7.45,1.02Z"
+        fill="#104e58"
+      />
+      <path
+        d="M33.44,21.34c-1.46-2.65-4.92-3.39-7.35-1.59l-.28,.21,.41,.89h0c2.23-.52,4.59-.11,6.51,1.15l.71-.66Z"
+        fill="#104e58"
+      />
+      <path
+        d="M19.49,14.23c-1.34-.06-3.99,.27-5.49,2.77"
+        fill="none"
+        stroke="#104e58"
+        strokeLinecap="round"
+        strokeWidth="1.8"
+      />
+      <path
+        d="M29,14.72c1.34-.06,3.99,.27,5.49,2.77"
+        fill="none"
+        stroke="#104e58"
+        strokeLinecap="round"
+        strokeWidth="1.8"
+      />
+      <path
+        d="M31.59,26h-15.18c-.69,0-1.18,.76-.93,1.48,1.1,3.13,3.24,7.47,8.51,7.47s7.42-4.34,8.51-7.47c.25-.72-.24-1.48-.93-1.48Z"
+        fill="#2199ac"
+      />
+      <path
+        d="M24,30c-4,0-6.62,1.74-5,3,.91,.71,3,1.49,5,1.5,2,0,4.26-.76,5-1.5,1.26-1.26-1-3-5-3Z"
+        fill="#d5f9fe"
+      />
+      <path
+        d="M31.56,25.1h-15.11c-1.4,0-2.47,1.38-1.97,2.76,.58,1.61,1.46,3.6,2.94,5.21,1.51,1.63,3.63,2.83,6.59,2.83s5.08-1.2,6.59-2.83c1.48-1.6,2.36-3.6,2.94-5.21,.5-1.38-.57-2.76-1.97-2.76Zm-2.29,6.74c-1.21,1.31-2.87,2.26-5.26,2.26s-4.06-.95-5.26-2.26c-1.24-1.33-2.02-3.06-2.57-4.59-.05-.15,.05-.35,.28-.35h15.11c.22,0,.33,.2,.28,.35-.55,1.53-1.33,3.26-2.57,4.59Z"
+        fill="#104e58"
+      />
+    </svg>
+  ),
+};
+
+/**
+ * A LinkedIn post embed component with professional styling.
+ * Displays author info and content with optional repost action.
+ *
+ * Features:
+ * - Author avatar with headline
+ * - Multi-line content with hashtag support
+ * - Optional post image
+ * - Expandable content with "...more" button
+ * - LinkedIn icon link to original post (optional)
+ * - Repost button in footer (optional, footer only shows if repostUrl provided)
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <LinkedInPost
+ *   data={{
+ *     author: "Manifest",
+ *     headline: "Building the future of AI",
+ *     avatar: "M",
+ *     content: "Excited to share our latest update!",
+ *     time: "2h",
+ *     image: "https://images.pexels.com/photos/417173/pexels-photo-417173.jpeg"
+ *   }}
+ *   actions={{
+ *     postUrl: "https://linkedin.com/posts/...",
+ *     repostUrl: "https://linkedin.com/shareArticle?..."
+ *   }}
+ *   appearance={{
+ *     maxLines: 3
+ *   }}
+ * />
+ * ```
+ */
+export function LinkedInPost({ data, appearance }: LinkedInPostProps) {
+  const resolved: NonNullable<LinkedInPostProps['data']> = data ?? demoLinkedInPost;
+  const {
+    author,
+    headline,
+    avatar,
+    content,
+    time,
+    image,
+    reactions,
+    topReactions,
+    comments,
+    reposts,
+    postUrl,
+    repostUrl,
+  } = resolved;
+
+  const { maxLines = 3 } = appearance ?? {};
+
+  const hasEngagement = reactions || comments || reposts;
+
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [isTruncated, setIsTruncated] = useState(false);
+  const contentRef = useRef<HTMLParagraphElement>(null);
+
+  useEffect(() => {
+    const el = contentRef.current;
+    if (el) {
+      // Check if content is truncated
+      setIsTruncated(el.scrollHeight > el.clientHeight);
+    }
+  }, [content, maxLines]);
+
+  const handleExpand = () => {
+    setIsExpanded(true);
+  };
+
+  return (
+    <div className="rounded-xl border bg-card">
+      <div className="p-4">
+        <div className="flex gap-3">
+          {avatar && (
+            <div className="h-12 w-12 rounded-full bg-[#0A66C2] text-white flex items-center justify-center font-semibold shrink-0">
+              {avatar}
+            </div>
+          )}
+          <div className="flex-1 min-w-0">
+            <div className="flex items-start justify-between">
+              <div>
+                <p className="font-semibold text-sm">{author}</p>
+                <p className="text-xs text-muted-foreground line-clamp-1">{headline}</p>
+                <p className="text-xs text-muted-foreground">{time}</p>
+              </div>
+              {postUrl && (
+                <a
+                  href={postUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-[#0A66C2] hover:text-[#004182] transition-colors"
+                  aria-label="View on LinkedIn"
+                >
+                  <LinkedInIcon className="h-5 w-5" />
+                </a>
+              )}
+            </div>
+          </div>
+        </div>
+        <div className="mt-3">
+          <p
+            ref={contentRef}
+            className="text-sm whitespace-pre-wrap"
+            style={
+              !isExpanded
+                ? {
+                    WebkitLineClamp: maxLines,
+                    display: '-webkit-box',
+                    WebkitBoxOrient: 'vertical',
+                    overflow: 'hidden',
+                  }
+                : undefined
+            }
+          >
+            {content ? formatContent(content) : null}
+          </p>
+          {isTruncated && !isExpanded && (
+            <button
+              onClick={handleExpand}
+              className="text-sm text-muted-foreground hover:text-foreground transition-colors cursor-pointer"
+            >
+              ...more
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Image section */}
+      {image && (
+        <div className="w-full">
+          <img src={image} alt="Post image" className="w-full object-cover max-h-[400px]" />
+        </div>
+      )}
+
+      {/* Engagement stats - reactions, comments, reposts */}
+      {hasEngagement && (
+        <div className="px-4 py-2 flex items-center justify-between text-xs text-muted-foreground">
+          <div className="flex items-center gap-1">
+            {topReactions && topReactions.length > 0 && (
+              <div className="flex -space-x-1">
+                {topReactions.slice(0, 3).map((type, idx) => (
+                  <div
+                    key={type}
+                    className="ring-2 ring-card rounded-full"
+                    style={{ zIndex: 3 - idx }}
+                  >
+                    {reactionIcons[type]}
+                  </div>
+                ))}
+              </div>
+            )}
+            {reactions && <span className="ml-1">{reactions}</span>}
+          </div>
+          <div className="flex items-center gap-3">
+            {comments && <span>{comments} comments</span>}
+            {reposts && <span>{reposts} reposts</span>}
+          </div>
+        </div>
+      )}
+
+      {/* Footer with repost button - only shows if repostUrl is provided */}
+      {repostUrl && (
+        <div className="px-4 py-2 border-t flex justify-end">
+          <a
+            href={repostUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center gap-2 px-4 py-2 hover:bg-muted rounded-md transition-colors text-sm text-muted-foreground"
+          >
+            <Repeat2 className="h-5 w-5" />
+            <span>Repost</span>
+          </a>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/ui/x-post.tsx b/src/components/ui/x-post.tsx
new file mode 100644
index 0000000..a3873db
--- /dev/null
+++ b/src/components/ui/x-post.tsx
@@ -0,0 +1,146 @@
+import { Heart, MessageCircle, Repeat2, Share, Bookmark } from "lucide-react"
+import { demoXPost } from './demo/social'
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * XPostProps
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Props for the XPost component, which displays an X (Twitter)-style post
+ * with author info, content, and engagement metrics.
+ */
+export interface XPostProps {
+  data?: {
+    /** Author's display name. */
+    author?: string
+    /** Author's handle/username (without the @ symbol). */
+    username?: string
+    /** Avatar letter fallback or image URL for the profile picture. */
+    avatar?: string
+    /** Post text content. */
+    content?: string
+    /** Time since posted (e.g., "2h"). */
+    time?: string
+    /** Formatted like count (e.g., "1.2K"). */
+    likes?: string
+    /** Formatted retweet/repost count. */
+    retweets?: string
+    /** Formatted reply count. */
+    replies?: string
+    /** Formatted view count (e.g., "45.2K"). */
+    views?: string
+    /** Whether the author has a verified badge. */
+    verified?: boolean
+  }
+}
+
+/**
+ * An X (Twitter) post embed component with engagement metrics.
+ * Displays author info, content, and interactive action buttons.
+ *
+ * Features:
+ * - Author avatar, name, and username
+ * - Verified badge support
+ * - Engagement metrics (likes, retweets, replies, views)
+ * - Interactive action buttons (reply, retweet, like, bookmark, share)
+ * - Time display
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <XPost
+ *   data={{
+ *     author: "John Doe",
+ *     username: "johndoe",
+ *     avatar: "J",
+ *     content: "Hello world! This is my first post.",
+ *     time: "2h",
+ *     likes: "1.2K",
+ *     retweets: "234",
+ *     replies: "56",
+ *     views: "45.2K",
+ *     verified: true
+ *   }}
+ * />
+ * ```
+ */
+export function XPost({ data }: XPostProps) {
+  const resolved: NonNullable<XPostProps['data']> = data ?? demoXPost
+  const author = resolved?.author
+  const username = resolved?.username
+  const avatar = resolved?.avatar
+  const content = resolved?.content
+  const time = resolved?.time
+  const likes = resolved?.likes
+  const retweets = resolved?.retweets
+  const replies = resolved?.replies
+  const views = resolved?.views
+  const verified = resolved?.verified
+
+  if (!author && !content) {
+    return null
+  }
+
+  return (
+    <div className="rounded-xl border bg-card p-4">
+      <div className="flex gap-3">
+        {avatar && (
+          <div className="h-10 w-10 rounded-full bg-foreground text-background flex items-center justify-center font-semibold text-sm shrink-0">
+            {avatar}
+          </div>
+        )}
+        <div className="flex-1 min-w-0">
+          {(author || username || time) && (
+            <div className="flex items-center gap-1 flex-wrap">
+              {author && <span className="font-bold text-sm">{author}</span>}
+              {verified && (
+                <svg className="h-4 w-4 text-blue-500" viewBox="0 0 24 24" fill="currentColor">
+                  <path d="M22.5 12.5c0-1.58-.875-2.95-2.148-3.6.154-.435.238-.905.238-1.4 0-2.21-1.71-3.998-3.818-3.998-.47 0-.92.084-1.336.25C14.818 2.415 13.51 1.5 12 1.5s-2.816.917-3.437 2.25c-.415-.165-.866-.25-1.336-.25-2.11 0-3.818 1.79-3.818 4 0 .494.083.964.237 1.4-1.272.65-2.147 2.018-2.147 3.6 0 1.495.782 2.798 1.942 3.486-.02.17-.032.34-.032.514 0 2.21 1.708 4 3.818 4 .47 0 .92-.086 1.335-.25.62 1.334 1.926 2.25 3.437 2.25 1.512 0 2.818-.916 3.437-2.25.415.163.865.248 1.336.248 2.11 0 3.818-1.79 3.818-4 0-.174-.012-.344-.033-.513 1.158-.687 1.943-1.99 1.943-3.484zm-6.616-3.334l-4.334 6.5c-.145.217-.382.334-.625.334-.143 0-.288-.04-.416-.126l-.115-.094-2.415-2.415c-.293-.293-.293-.768 0-1.06s.768-.294 1.06 0l1.77 1.767 3.825-5.74c.23-.345.696-.436 1.04-.207.346.23.44.696.21 1.04z" />
+                </svg>
+              )}
+              {username && <span className="text-muted-foreground text-sm">@{username}</span>}
+              {time && <span className="text-muted-foreground text-sm">· {time}</span>}
+            </div>
+          )}
+          {content && <p className="text-sm mt-1 whitespace-pre-wrap">{content}</p>}
+          {(replies || retweets || likes || views) && (
+            <div className="flex items-center justify-between mt-3 text-muted-foreground max-w-md">
+              {replies !== undefined && (
+                <button aria-label="Reply" className="flex items-center gap-1.5 hover:text-blue-500 transition-colors text-xs cursor-pointer">
+                  <MessageCircle className="h-4 w-4" />
+                  <span>{replies}</span>
+                </button>
+              )}
+              {retweets !== undefined && (
+                <button aria-label="Repost" className="flex items-center gap-1.5 hover:text-green-500 transition-colors text-xs cursor-pointer">
+                  <Repeat2 className="h-4 w-4" />
+                  <span>{retweets}</span>
+                </button>
+              )}
+              {likes !== undefined && (
+                <button aria-label="Like" className="flex items-center gap-1.5 hover:text-pink-500 transition-colors text-xs cursor-pointer">
+                  <Heart className="h-4 w-4" />
+                  <span>{likes}</span>
+                </button>
+              )}
+              {views !== undefined && (
+                <button aria-label="Views" className="flex items-center gap-1.5 hover:text-blue-500 transition-colors text-xs cursor-pointer">
+                  <svg className="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                    <path d="M3 12h4l3 8 4-16 3 8h4" />
+                  </svg>
+                  <span>{views}</span>
+                </button>
+              )}
+              <button aria-label="Bookmark" className="hover:text-blue-500 transition-colors cursor-pointer">
+                <Bookmark className="h-4 w-4" />
+              </button>
+              <button aria-label="Share" className="hover:text-blue-500 transition-colors cursor-pointer">
+                <Share className="h-4 w-4" />
+              </button>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/ui/youtube-post.tsx b/src/components/ui/youtube-post.tsx
new file mode 100644
index 0000000..8f2ed60
--- /dev/null
+++ b/src/components/ui/youtube-post.tsx
@@ -0,0 +1,194 @@
+"use client"
+
+import { useState } from "react"
+import { Bookmark, MoreHorizontal, Share, EyeOff, Flag } from "lucide-react"
+import { demoYouTubePost } from './demo/social'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * YouTubePostProps
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Props for the YouTubePost component, which displays a YouTube video embed
+ * with thumbnail preview and click-to-play functionality.
+ */
+export interface YouTubePostProps {
+  data?: {
+    /** YouTube channel name. */
+    channel?: string
+    /** Channel avatar letter fallback or image URL. */
+    avatar?: string
+    /** Video title. */
+    title?: string
+    /** Formatted view count (e.g., "1M views"). */
+    views?: string
+    /** Time since video was published (e.g., "2 weeks ago"). */
+    time?: string
+    /** Video duration in MM:SS or HH:MM:SS format. */
+    duration?: string
+    /** URL of the video thumbnail image. */
+    thumbnail?: string
+    /** Formatted subscriber count for the channel. */
+    subscribers?: string
+    /** Whether the channel has a verified badge. */
+    verified?: boolean
+    /** YouTube video ID used for embedding the player. */
+    videoId?: string
+  }
+}
+
+/**
+ * A YouTube video embed component with thumbnail preview and playback.
+ * Click the play button to load and play the embedded video.
+ *
+ * Features:
+ * - Thumbnail preview with YouTube play button
+ * - Duration badge overlay
+ * - Channel avatar and info
+ * - Verified channel badge
+ * - View count and publish time
+ * - Click-to-play video embedding
+ * - Dropdown menu (save, share, not interested, report)
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <YouTubePost
+ *   data={{
+ *     channel: "Tech Channel",
+ *     avatar: "T",
+ *     title: "How to build amazing UIs",
+ *     views: "1M views",
+ *     time: "2 weeks ago",
+ *     duration: "18:42",
+ *     thumbnail: "https://img.youtube.com/vi/abc123/maxresdefault.jpg",
+ *     verified: true,
+ *     videoId: "abc123"
+ *   }}
+ * />
+ * ```
+ */
+export function YouTubePost({ data }: YouTubePostProps) {
+  const resolved: NonNullable<YouTubePostProps['data']> = data ?? demoYouTubePost
+  const channel = resolved?.channel
+  const avatar = resolved?.avatar
+  const title = resolved?.title
+  const views = resolved?.views
+  const time = resolved?.time
+  const duration = resolved?.duration
+  const thumbnail = resolved?.thumbnail
+  const verified = resolved?.verified
+  const videoId = resolved?.videoId
+
+  const [isPlaying, setIsPlaying] = useState(false)
+
+  if (!title && !thumbnail && !videoId) {
+    return null
+  }
+
+  return (
+    <div className="rounded-xl border bg-card overflow-hidden">
+      {/* Thumbnail / Video */}
+      {(thumbnail || videoId) && (
+        <div className="relative aspect-video bg-black">
+          {isPlaying && videoId ? (
+            <iframe
+              className="w-full h-full"
+              src={`https://www.youtube.com/embed/${videoId}?autoplay=1`}
+              title={title ?? 'YouTube video'}
+              allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+              allowFullScreen
+            />
+          ) : (
+            <>
+              {thumbnail && (
+                <img src={thumbnail} alt={title ? `Video thumbnail: ${title}` : 'Video thumbnail'} className="w-full h-full object-cover" />
+              )}
+
+              {/* YouTube play button overlay */}
+              {videoId && (
+                <button
+                  className="absolute inset-0 flex items-center justify-center"
+                  onClick={() => setIsPlaying(true)}
+                  aria-label="Play video"
+                >
+                  <svg className="h-10 w-14 cursor-pointer hover:scale-105 transition-transform" viewBox="0 0 1024 721">
+                    <path fill="#FF0000" d="M1013,156.3c0,0-10-70.4-40.6-101.4C933.6,14.2,890,14,870.1,11.6C727.1,1.3,512.7,1.3,512.7,1.3h-0.4c0,0-214.4,0-357.4,10.3C135,14,91.4,14.2,52.6,54.9C22,85.9,12,156.3,12,156.3S1.8,238.9,1.8,321.6v77.5C1.8,481.8,12,564.4,12,564.4s10,70.4,40.6,101.4c38.9,40.7,89.9,39.4,112.6,43.7c81.7,7.8,347.3,10.3,347.3,10.3s214.6-0.3,357.6-10.7c20-2.4,63.5-2.6,102.3-43.3c30.6-31,40.6-101.4,40.6-101.4s10.2-82.7,10.2-165.3v-77.5C1023.2,238.9,1013,156.3,1013,156.3z M407,493V206l276,144L407,493z"/>
+                    <path fill="#FFFFFF" d="M407,493l276-143L407,206V493z"/>
+                  </svg>
+                </button>
+              )}
+
+              {/* Duration badge */}
+              {duration && (
+                <div className="absolute bottom-2 right-2 bg-black/80 text-white text-xs px-1.5 py-0.5 rounded font-medium">
+                  {duration}
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      )}
+
+      {/* Video info */}
+      {(channel || title) && (
+        <div className="p-3">
+          <div className="flex gap-3">
+            {avatar && (
+              <div className="h-9 w-9 rounded-full bg-red-600 text-white flex items-center justify-center font-semibold text-sm shrink-0">
+                {avatar}
+              </div>
+            )}
+            <div className="flex-1 min-w-0">
+              {title && <h3 className="font-semibold text-sm line-clamp-2 leading-tight">{title}</h3>}
+              {channel && (
+                <div className="mt-1.5 flex items-center gap-1 text-xs text-muted-foreground">
+                  <span>{channel}</span>
+                  {verified && (
+                    <svg className="h-3.5 w-3.5" viewBox="0 0 24 24" fill="currentColor">
+                      <path d="M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10 10-4.5 10-10S17.5 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z" />
+                    </svg>
+                  )}
+                </div>
+              )}
+              {(views || time) && (
+                <p className="text-xs text-muted-foreground">
+                  {views}{views && time && ' • '}{time}
+                </p>
+              )}
+            </div>
+            <DropdownMenu>
+              <DropdownMenuTrigger render={<button className="text-muted-foreground hover:text-foreground shrink-0 transition-colors cursor-pointer" />}><MoreHorizontal className="h-5 w-5" /></DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuItem>
+                  <Bookmark className="mr-2 h-4 w-4" />
+                  Save to Watch later
+                </DropdownMenuItem>
+                <DropdownMenuItem>
+                  <Share className="mr-2 h-4 w-4" />
+                  Share
+                </DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem>
+                  <EyeOff className="mr-2 h-4 w-4" />
+                  Not interested
+                </DropdownMenuItem>
+                <DropdownMenuItem>
+                  <Flag className="mr-2 h-4 w-4" />
+                  Report
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/src/context/auth-context.tsx b/src/context/auth-context.tsx
new file mode 100644
index 0000000..cd7b706
--- /dev/null
+++ b/src/context/auth-context.tsx
@@ -0,0 +1,71 @@
+import {
+  createContext,
+  useContext,
+  type ReactNode,
+} from "react";
+import axios from "axios";
+import { useQuery } from "@tanstack/react-query";
+
+import { client, type ContextMe } from "@/client";
+
+type AuthContextValue = {
+  me: ContextMe | null;
+  user: ContextMe | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => Promise<ContextMe | null>;
+};
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+async function fetchMe() {
+  try {
+    const response = await client.authMe();
+    return response.data;
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.status === 401) {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const { data, error, isLoading, refetch } = useQuery({
+    queryKey: ["auth", "me"],
+    queryFn: fetchMe,
+    retry: false,
+  });
+
+  const me = data ?? null;
+
+  return (
+    <AuthContext.Provider
+      value={{
+        me,
+        user: me,
+        isAuthenticated: me !== null,
+        isLoading,
+        error,
+        refresh: async () => {
+          const result = await refetch();
+          return result.data ?? null;
+        },
+      }}
+    >
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+
+  if (!context) {
+    throw new Error("useAuth must be used within AuthProvider.");
+  }
+
+  return context;
+}
diff --git a/src/hooks/use-channel.tsx b/src/hooks/use-channel.tsx
new file mode 100644
index 0000000..4e81a09
--- /dev/null
+++ b/src/hooks/use-channel.tsx
@@ -0,0 +1,96 @@
+import { useCallback, createContext, useEffect, useRef } from "react";
+
+import { channelSocket, type WsOutEvent } from "@/socket";
+import { useAuth } from "@/context/auth-context";
+
+type Handler = (event: WsOutEvent) => void;
+
+const ChannelSocketContext = createContext<null>(null);
+
+/**
+ * Global channel socket lifecycle.
+ * Connects once when the user is authenticated and keeps the connection alive
+ * for the entire app lifetime. Unmounting the provider disconnects.
+ */
+export function ChannelSocketProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const connectedRef = useRef(false);
+
+  useEffect(() => {
+    if (isLoading) return;
+    if (isAuthenticated && !connectedRef.current) {
+      connectedRef.current = true;
+      channelSocket.connect();
+    }
+  }, [isAuthenticated, isLoading]);
+
+  // Disconnect only on page unload
+  useEffect(() => {
+    const handleUnload = () => channelSocket.disconnect();
+    window.addEventListener("beforeunload", handleUnload);
+    return () => {
+      window.removeEventListener("beforeunload", handleUnload);
+      channelSocket.disconnect();
+      connectedRef.current = false;
+    };
+  }, []);
+
+  return <ChannelSocketContext value={null}>{children}</ChannelSocketContext>;
+}
+
+/**
+ * Subscribe to channel socket events.
+ * Does NOT manage connection lifecycle — that's the provider's job.
+ */
+export function useChannelSocket() {
+  const handlersRef = useRef(new Set<Handler>());
+
+  // Register the single relay handler once (lazy ref init)
+  const relayRef = useRef<(() => void) | null>(null);
+  // eslint-disable-next-line react-hooks/refs
+  if (!relayRef.current) {
+    relayRef.current = channelSocket.on((event) => {
+      for (const handler of handlersRef.current) {
+        handler(event);
+      }
+    });
+  }
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      relayRef.current?.();
+      relayRef.current = null;
+    };
+  }, []);
+
+  const subscribe = useCallback(async (roomId: string) => {
+    await channelSocket.subscribe(roomId);
+  }, []);
+
+  const unsubscribe = useCallback(async (roomId: string) => {
+    await channelSocket.unsubscribe(roomId);
+  }, []);
+
+  const send = useCallback(async <T = unknown>(message: {
+    type: string;
+    [key: string]: unknown;
+  }) => {
+    return channelSocket.request<T>(message);
+  }, []);
+
+  const onEvent = useCallback((handler: Handler) => {
+    handlersRef.current.add(handler);
+    return () => {
+      handlersRef.current.delete(handler);
+    };
+  }, []);
+
+  return { subscribe, unsubscribe, send, onEvent };
+}
+
+export type { WsOutEvent };
diff --git a/src/hooks/use-message-cache.ts b/src/hooks/use-message-cache.ts
new file mode 100644
index 0000000..2889373
--- /dev/null
+++ b/src/hooks/use-message-cache.ts
@@ -0,0 +1,88 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import type { MessageNewService } from "@/socket";
+import { MessageRepository } from "@/lib/db/repository";
+
+/**
+ * Persists messages to IndexedDB and loads cached messages on room change.
+ * Does NOT replace the React state — acts as a side-effect cache layer.
+ */
+export function useMessageCache(roomId: string | undefined) {
+  const lastPersistedSeq = useRef(0);
+
+  /** Load cached messages from IndexedDB. Returns empty if none cached. */
+  const loadCached = useCallback(
+    async (limit = 50): Promise<MessageNewService[]> => {
+      if (!roomId) return [];
+      try {
+        return await MessageRepository.getMessages(roomId, undefined, limit);
+      } catch {
+        return [];
+      }
+    },
+    [roomId],
+  );
+
+  /** Persist a batch of messages to IndexedDB. */
+  const persistBatch = useCallback(
+    async (msgs: MessageNewService[]) => {
+      if (!roomId || msgs.length === 0) return;
+      try {
+        await MessageRepository.saveMessages(roomId, msgs);
+        const maxSeq = Math.max(...msgs.map((m) => m.seq));
+        if (maxSeq > lastPersistedSeq.current) {
+          lastPersistedSeq.current = maxSeq;
+        }
+      } catch {
+        // IndexedDB write can fail silently
+      }
+    },
+    [roomId],
+  );
+
+  /** Persist a single new message (from WS event). */
+  const persistMessage = useCallback(
+    async (msg: MessageNewService) => {
+      if (!roomId) return;
+      try {
+        await MessageRepository.saveMessages(roomId, [msg]);
+        if (msg.seq > lastPersistedSeq.current) {
+          lastPersistedSeq.current = msg.seq;
+        }
+      } catch {
+        // silent
+      }
+    },
+    [roomId],
+  );
+
+  /** Get last known seq for this room from IndexedDB. */
+  const getLastSeq = useCallback(async (): Promise<number> => {
+    if (!roomId) return 0;
+    try {
+      return await MessageRepository.getLastSeq(roomId);
+    } catch {
+      return 0;
+    }
+  }, [roomId]);
+
+  /** Clear cached messages for this room. */
+  const clearCache = useCallback(async () => {
+    if (!roomId) return;
+    try {
+      await MessageRepository.clearRoom(roomId);
+      lastPersistedSeq.current = 0;
+    } catch {
+      // silent
+    }
+  }, [roomId]);
+
+  // Prune old rooms on mount
+  useEffect(() => {
+    MessageRepository.prune().catch(() => {});
+  }, []);
+
+  return useMemo(
+    () => ({ loadCached, persistBatch, persistMessage, getLastSeq, clearCache }),
+    [loadCached, persistBatch, persistMessage, getLastSeq, clearCache],
+  );
+}
diff --git a/src/hooks/use-toast.ts b/src/hooks/use-toast.ts
new file mode 100644
index 0000000..d1fe122
--- /dev/null
+++ b/src/hooks/use-toast.ts
@@ -0,0 +1,23 @@
+import { toast as sonnerToast } from "sonner";
+
+type ToastOptions = {
+  title: string;
+  description?: string;
+  variant?: "default" | "destructive";
+};
+
+export function useToast() {
+  return {
+    toast: (options: ToastOptions) => {
+      if (options.variant === "destructive") {
+        sonnerToast.error(options.title, {
+          description: options.description,
+        });
+      } else {
+        sonnerToast(options.title, {
+          description: options.description,
+        });
+      }
+    },
+  };
+}
\ No newline at end of file
diff --git a/src/lib/ir/mention-chip.tsx b/src/lib/ir/mention-chip.tsx
new file mode 100644
index 0000000..357d654
--- /dev/null
+++ b/src/lib/ir/mention-chip.tsx
@@ -0,0 +1,53 @@
+import { useCallback } from 'react';
+import { AtSign, Hash, User, GitBranch, Bug } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import type { MentionData } from './parser';
+
+const entityIcons: Record<string, React.ComponentType<{ className?: string }>> = {
+  user: User,
+  repo: GitBranch,
+  issue: Bug,
+  pr: GitBranch,
+  room: Hash,
+};
+
+const entityColors: Record<string, string> = {
+  user: 'text-blue-600 dark:text-blue-400 bg-blue-50 dark:bg-blue-950',
+  repo: 'text-emerald-600 dark:text-emerald-400 bg-emerald-50 dark:bg-emerald-950',
+  issue: 'text-orange-600 dark:text-orange-400 bg-orange-50 dark:bg-orange-950',
+  pr: 'text-purple-600 dark:text-purple-400 bg-purple-50 dark:bg-purple-950',
+  room: 'text-sky-600 dark:text-sky-400 bg-sky-50 dark:bg-sky-950',
+};
+
+interface Props {
+  entityType: string;
+  entityId: string;
+  entityLabel: string;
+  onClick?: (mention: MentionData) => void;
+}
+
+export function MentionChip({ entityType, entityId, entityLabel, onClick }: Props) {
+  const Icon = entityIcons[entityType] ?? AtSign;
+  const colorClass = entityColors[entityType] ?? 'text-muted-foreground bg-muted';
+
+  const handleClick = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    onClick?.({ entityType, entityId, entityLabel });
+  }, [entityType, entityId, entityLabel, onClick]);
+
+  return (
+    <span
+      className={cn(
+        'inline-flex cursor-pointer items-center gap-1 rounded-md px-1.5 py-0.5 text-xs font-medium transition-colors hover:opacity-80',
+        colorClass,
+      )}
+      onClick={handleClick}
+      role="button"
+      tabIndex={0}
+    >
+      <Icon className="size-3" />
+      {entityLabel}
+    </span>
+  );
+}
diff --git a/src/lib/ir/mention-renderer.tsx b/src/lib/ir/mention-renderer.tsx
new file mode 100644
index 0000000..d00ac9a
--- /dev/null
+++ b/src/lib/ir/mention-renderer.tsx
@@ -0,0 +1,41 @@
+import { memo } from 'react';
+import { parseMentions } from './parser';
+import { MentionChip } from './mention-chip';
+import type { MentionData } from './parser';
+
+interface Props {
+  content: string;
+  className?: string;
+  onMentionClick?: (mention: MentionData) => void;
+}
+
+/**
+ * Renders message content with inline mention chips.
+ * Text segments render as plain text; mentions render as clickable chips.
+ */
+export const MentionRenderer = memo(function MentionRenderer({
+  content,
+  className,
+  onMentionClick,
+}: Props) {
+  const segments = parseMentions(content);
+
+  return (
+    <span className={className}>
+      {segments.map((seg, i) => {
+        if (seg.type === 'mention' && seg.mention) {
+          return (
+            <MentionChip
+              key={`${seg.mention.entityId}-${i}`}
+              entityType={seg.mention.entityType}
+              entityId={seg.mention.entityId}
+              entityLabel={seg.mention.entityLabel}
+              onClick={onMentionClick}
+            />
+          );
+        }
+        return <span key={i}>{seg.content}</span>;
+      })}
+    </span>
+  );
+});
diff --git a/src/page/auth/components.tsx b/src/page/auth/components.tsx
new file mode 100644
index 0000000..ea2caf4
--- /dev/null
+++ b/src/page/auth/components.tsx
@@ -0,0 +1,179 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { Apple, Eye, EyeOff, Globe, RotateCw, Send } from "lucide-react";
+
+import { client, type CaptchaResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export function Divider() {
+  return (
+    <div className="my-5 flex items-center gap-4 text-xs font-medium uppercase text-zinc-400">
+      <div className="h-px flex-1 bg-zinc-200" />
+      <span>or</span>
+      <div className="h-px flex-1 bg-zinc-200" />
+    </div>
+  );
+}
+
+export function SocialButtons() {
+  return (
+    <div className="mt-6 grid grid-cols-3 gap-3">
+      <Button className="h-11 rounded-lg border-zinc-200 bg-white text-zinc-950 hover:bg-zinc-50" type="button" variant="outline">
+        <Apple className="size-5 fill-current" aria-hidden="true" />
+        <span className="sr-only">Continue with Apple</span>
+      </Button>
+      <Button className="h-11 rounded-lg border-zinc-200 bg-white text-zinc-950 hover:bg-zinc-50" type="button" variant="outline">
+        <Globe className="size-5 text-red-500" aria-hidden="true" />
+        <span className="sr-only">Continue with Google</span>
+      </Button>
+      <Button className="h-11 rounded-lg border-zinc-200 bg-white text-sky-500 hover:bg-zinc-50" type="button" variant="outline">
+        <Send className="size-5 fill-current" aria-hidden="true" />
+        <span className="sr-only">Continue with Twitter</span>
+      </Button>
+    </div>
+  );
+}
+
+export function PasswordInput({
+  id,
+  name,
+  placeholder,
+}: {
+  id: string;
+  name: string;
+  placeholder: string;
+}) {
+  const [visible, setVisible] = useState(false);
+
+  return (
+    <div className="relative">
+      <Input
+        className="h-11 rounded-lg border-zinc-200 pr-11 text-sm placeholder:text-zinc-400 focus-visible:ring-zinc-200"
+        id={id}
+        name={name}
+        placeholder={placeholder}
+        required
+        type={visible ? "text" : "password"}
+      />
+      <Button
+        aria-label={visible ? "Hide password" : "Show password"}
+        className="absolute right-1.5 top-1/2 size-9 -translate-y-1/2 text-zinc-500 hover:bg-transparent"
+        onClick={() => setVisible((current) => !current)}
+        type="button"
+        variant="ghost"
+      >
+        {visible ? <EyeOff className="size-4" /> : <Eye className="size-4" />}
+      </Button>
+    </div>
+  );
+}
+
+export function CaptchaField({
+  onPublicKey,
+}: {
+  onPublicKey?: (publicKey: string) => void;
+}) {
+  const [captcha, setCaptcha] = useState<CaptchaResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const loadCaptcha = async () => {
+    setLoading(true);
+    try {
+      const response = await client.authCaptcha({
+        w: 140,
+        h: 44,
+        dark: false,
+        rsa: true,
+      });
+      setCaptcha(response.data);
+      if (response.data.rsa?.public_key) {
+        onPublicKey?.(response.data.rsa.public_key);
+      }
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    void loadCaptcha();
+  }, []);
+
+  const src = captcha?.base64?.startsWith("data:")
+    ? captcha.base64
+    : `data:image/png;base64,${captcha?.base64 ?? ""}`;
+
+  return (
+    <div className="space-y-2">
+      <Label className="text-sm font-semibold text-zinc-950" htmlFor="captcha">
+        Captcha
+      </Label>
+      <div className="flex gap-3">
+        <Input
+          className="h-11 rounded-lg border-zinc-200 text-sm placeholder:text-zinc-400 focus-visible:ring-zinc-200"
+          id="captcha"
+          name="captcha"
+          placeholder="Enter captcha..."
+          required
+        />
+        <button
+          aria-label="Refresh captcha"
+          className="grid h-11 w-30 shrink-0 place-items-center rounded-lg border border-zinc-200 bg-zinc-50 text-zinc-500"
+          disabled={loading}
+          onClick={() => void loadCaptcha()}
+          type="button"
+        >
+          {captcha ? (
+            <img alt="Captcha" className="h-9 max-w-28 object-contain" src={src} />
+          ) : (
+            <RotateCw className="size-4" />
+          )}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export function TextField({
+  id,
+  label,
+  name,
+  placeholder,
+  type = "text",
+}: {
+  id: string;
+  label: string;
+  name: string;
+  placeholder: string;
+  type?: string;
+}) {
+  return (
+    <div className="space-y-2">
+      <Label className="text-sm font-semibold text-zinc-950" htmlFor={id}>
+        {label}
+      </Label>
+      <Input
+        className="h-11 rounded-lg border-zinc-200 text-sm placeholder:text-zinc-400 focus-visible:ring-zinc-200"
+        id={id}
+        name={name}
+        placeholder={placeholder}
+        required
+        type={type}
+      />
+    </div>
+  );
+}
+
+export function FormMessage({ children, tone }: { children: ReactNode; tone: "error" | "success" }) {
+  return (
+    <p
+      className={
+        tone === "error"
+          ? "rounded-lg bg-red-50 px-3 py-2 text-sm text-red-600"
+          : "rounded-lg bg-emerald-50 px-3 py-2 text-sm text-emerald-700"
+      }
+    >
+      {children}
+    </p>
+  );
+}
diff --git a/src/page/auth/forgot-password.tsx b/src/page/auth/forgot-password.tsx
new file mode 100644
index 0000000..47c478e
--- /dev/null
+++ b/src/page/auth/forgot-password.tsx
@@ -0,0 +1,67 @@
+import { useState, type FormEvent } from "react";
+import { Link } from "react-router";
+
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { AuthHeader, AuthPanel } from "./layout";
+import { FormMessage, TextField } from "./components";
+import { fieldValue, getErrorMessage } from "./utils";
+
+export default function ForgotPasswordPage() {
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const [success, setSuccess] = useState("");
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSuccess("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+
+    try {
+      await client.authResetPasswordRequest({
+        email: fieldValue(form, "email"),
+      });
+      setSuccess("Password reset instructions have been sent.");
+    } catch (requestError) {
+      setError(getErrorMessage(requestError));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <AuthPanel>
+      <AuthHeader description="Enter your email to receive a reset link." title="Forgot password" />
+
+      <form className="relative mt-6 space-y-4" onSubmit={(event) => void handleSubmit(event)}>
+        <TextField
+          id="email"
+          label="E-Mail Address"
+          name="email"
+          placeholder="Enter your email..."
+          type="email"
+        />
+
+        {error && <FormMessage tone="error">{error}</FormMessage>}
+        {success && <FormMessage tone="success">{success}</FormMessage>}
+
+        <Button
+          className="h-11 w-full rounded-lg bg-zinc-950 text-base text-white shadow-inner shadow-white/10 hover:bg-zinc-800"
+          disabled={submitting}
+          type="submit"
+        >
+          {submitting ? "Please wait..." : "Send reset link"}
+        </Button>
+      </form>
+
+      <footer className="mt-6 text-center text-base text-zinc-500">
+        <Link className="font-semibold text-zinc-950" to="/auth/login">
+          Back to sign in
+        </Link>
+      </footer>
+    </AuthPanel>
+  );
+}
diff --git a/src/page/auth/layout.tsx b/src/page/auth/layout.tsx
new file mode 100644
index 0000000..876d2dc
--- /dev/null
+++ b/src/page/auth/layout.tsx
@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+import { Navigate, Outlet } from "react-router";
+
+import { useAuth } from "@/context/auth-context";
+
+function AuthLogo() {
+  return (
+    <div className="mx-auto grid size-12 place-items-center rounded-lg bg-gradient-to-b from-[oklch(0.45_0.24_290)] to-[oklch(0.55_0.24_290)] shadow-[0_14px_30px_rgba(134,59,255,0.24)]">
+      <div className="relative size-8 overflow-hidden rounded-sm bg-white/20">
+        <span className="absolute left-1.5 top-2 h-1 w-6 rounded-full bg-white" />
+        <span className="absolute left-1 top-3.5 h-1 w-7 rounded-full bg-white/90" />
+        <span className="absolute left-2 top-5 h-1 w-6 rounded-full bg-white/80" />
+      </div>
+    </div>
+  );
+}
+
+export function AuthPanel({ children }: { children: ReactNode }) {
+  return (
+    <section className="relative z-10 w-full max-w-[460px] rounded-lg bg-card px-6 py-8 shadow-[0_24px_64px_rgba(134,59,255,0.08)] sm:px-9">
+      <div className="pointer-events-none absolute inset-x-0 top-0 h-32 overflow-hidden rounded-t-lg">
+        <div className="absolute inset-0 bg-[linear-gradient(rgba(134,59,255,0.10)_1px,transparent_1px),linear-gradient(90deg,rgba(134,59,255,0.10)_1px,transparent_1px)] bg-[size:38px_38px] [mask-image:linear-gradient(to_bottom,black,transparent)]" />
+        <div className="absolute inset-x-10 top-0 h-24 bg-gradient-to-b from-[oklch(0.40_0.12_290)/0.15] to-transparent blur-2xl" />
+      </div>
+      {children}
+    </section>
+  );
+}
+
+export function AuthHeader({
+  title,
+  description,
+}: {
+  title: string;
+  description: string;
+}) {
+  return (
+    <header className="relative text-center">
+      <AuthLogo />
+      <h1 className="mt-6 text-2xl font-heading font-semibold tracking-normal text-foreground">
+        {title}
+      </h1>
+      <p className="mt-2 text-base text-muted-foreground">{description}</p>
+    </header>
+  );
+}
+
+export default function AuthLayout() {
+  const { isAuthenticated, isLoading } = useAuth();
+
+  if (isAuthenticated) {
+    return <Navigate replace to="/" />;
+  }
+
+  return (
+    <main className="min-h-svh bg-background px-4 py-6 text-foreground">
+      <div className="relative mx-auto grid min-h-[calc(100svh-3rem)] w-full max-w-5xl place-items-center overflow-hidden">
+        <div className="pointer-events-none absolute inset-0 bg-[linear-gradient(rgba(134,59,255,0.05)_1px,transparent_1px),linear-gradient(90deg,rgba(134,59,255,0.05)_1px,transparent_1px)] bg-[size:72px_72px] [mask-image:radial-gradient(circle_at_center,black,transparent_70%)]" />
+        <div className="pointer-events-none absolute inset-0 bg-[radial-gradient(circle_at_center,rgba(134,59,255,0.15),transparent_50%)]" />
+        {isLoading ? (
+          <div className="relative z-10 text-sm font-mono font-medium text-muted-foreground">
+            Loading...
+          </div>
+        ) : (
+          <Outlet />
+        )}
+      </div>
+    </main>
+  );
+}
\ No newline at end of file
diff --git a/src/page/auth/login.tsx b/src/page/auth/login.tsx
new file mode 100644
index 0000000..4e982ef
--- /dev/null
+++ b/src/page/auth/login.tsx
@@ -0,0 +1,211 @@
+import { useState, type FormEvent } from "react";
+import { Link, useNavigate } from "react-router";
+import axios from "axios";
+
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { useAuth } from "@/context/auth-context";
+import { AuthHeader, AuthPanel } from "./layout";
+import {
+  CaptchaField,
+  FormMessage,
+  PasswordInput,
+  TextField,
+} from "./components";
+import { encryptPassword, fieldValue, getErrorMessage, passwordValue } from "./utils";
+
+type LoginPayload = {
+  username: string;
+  password: string;
+  captcha: string;
+};
+
+function isTwoFactorRequired(error: unknown) {
+  return (
+    axios.isAxiosError(error) &&
+    (error.response?.status === 402 ||
+      error.response?.data?.error === "two-factor authentication required")
+  );
+}
+
+export default function LoginPage() {
+  const navigate = useNavigate();
+  const { refresh } = useAuth();
+  const [submitting, setSubmitting] = useState(false);
+  const [twoFactorSubmitting, setTwoFactorSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const [twoFactorError, setTwoFactorError] = useState("");
+  const [twoFactorOpen, setTwoFactorOpen] = useState(false);
+  const [pendingLogin, setPendingLogin] = useState<LoginPayload | null>(null);
+  const [publicKey, setPublicKey] = useState("");
+
+  const finishLogin = async (payload: LoginPayload, totpCode?: string) => {
+    await client.authLogin({
+      ...payload,
+      totp_code: totpCode || undefined,
+    });
+    await refresh();
+    navigate("/");
+  };
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+
+    try {
+      if (!publicKey) {
+        throw new Error("Captcha is not ready. Please refresh it and try again.");
+      }
+
+      const payload = {
+        username: fieldValue(form, "username"),
+        password: encryptPassword(publicKey, passwordValue(form, "password")),
+        captcha: fieldValue(form, "captcha"),
+      };
+
+      await finishLogin(payload);
+    } catch (requestError) {
+      if (isTwoFactorRequired(requestError)) {
+        const form = new FormData(event.currentTarget);
+        setPendingLogin({
+          username: fieldValue(form, "username"),
+          password: encryptPassword(publicKey, passwordValue(form, "password")),
+          captcha: fieldValue(form, "captcha"),
+        });
+        setTwoFactorError("");
+        setTwoFactorOpen(true);
+      } else {
+        setError(getErrorMessage(requestError));
+      }
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleTwoFactorSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (!pendingLogin) {
+      return;
+    }
+
+    setTwoFactorError("");
+    setTwoFactorSubmitting(true);
+
+    try {
+      const form = new FormData(event.currentTarget);
+      await finishLogin(pendingLogin, fieldValue(form, "totpCode"));
+    } catch (requestError) {
+      setTwoFactorError(getErrorMessage(requestError));
+    } finally {
+      setTwoFactorSubmitting(false);
+    }
+  };
+
+  return (
+    <AuthPanel>
+      <AuthHeader description="Please enter your details to sign in." title="Welcome back" />
+
+      <form className="relative space-y-4 mt-10" onSubmit={(event) => void handleSubmit(event)}>
+        <TextField
+          id="username"
+          label="Username or E-Mail Address"
+          name="username"
+          placeholder="Enter your username or email..."
+        />
+
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold text-zinc-950" htmlFor="password">
+            Password
+          </Label>
+          <PasswordInput id="password" name="password" placeholder="Enter your password..." />
+        </div>
+
+        <CaptchaField onPublicKey={setPublicKey} />
+
+        <div className="flex items-center justify-between gap-4 text-sm">
+          <label className="flex items-center gap-3 font-medium text-zinc-950">
+            <Checkbox className="size-4 rounded-[5px] border-zinc-200" name="remember" />
+            Remember me
+          </label>
+          <Link className="font-medium text-zinc-600 underline underline-offset-4" to="/auth/forgot-password">
+            Forgot password?
+          </Link>
+        </div>
+
+        {error && <FormMessage tone="error">{error}</FormMessage>}
+
+        <Button
+          className="h-11 w-full rounded-lg bg-zinc-950 text-base text-white shadow-inner shadow-white/10 hover:bg-zinc-800"
+          disabled={submitting}
+          type="submit"
+        >
+          {submitting ? "Please wait..." : "Sign in"}
+        </Button>
+      </form>
+
+      <footer className="mt-6 text-center text-base text-zinc-500">
+        Don&apos;t have an account yet?{" "}
+        <Link className="font-semibold text-zinc-950" to="/auth/register">
+          Sign Up
+        </Link>
+      </footer>
+
+      <Dialog open={twoFactorOpen} onOpenChange={setTwoFactorOpen}>
+        <DialogContent className="sm:max-w-90">
+          <DialogHeader>
+            <DialogTitle>Two-factor authentication</DialogTitle>
+            <DialogDescription>
+              Enter the 6-digit code from your authenticator app.
+            </DialogDescription>
+          </DialogHeader>
+
+          <form className="space-y-4" onSubmit={(event) => void handleTwoFactorSubmit(event)}>
+            <div className="space-y-2">
+              <Label className="text-sm font-semibold" htmlFor="totpCode">
+                Authentication code
+              </Label>
+              <Input
+                autoComplete="one-time-code"
+                autoFocus
+                className="h-11 text-center text-lg tracking-[0.35em]"
+                id="totpCode"
+                inputMode="numeric"
+                maxLength={6}
+                name="totpCode"
+                pattern="[0-9]{6}"
+                placeholder="000000"
+                required
+              />
+            </div>
+
+            {twoFactorError && <FormMessage tone="error">{twoFactorError}</FormMessage>}
+
+            <DialogFooter className="-mx-4 -mb-4">
+              <Button
+                className="h-10 bg-zinc-950 text-white hover:bg-zinc-800"
+                disabled={twoFactorSubmitting}
+                type="submit"
+              >
+                {twoFactorSubmitting ? "Verifying..." : "Verify"}
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+    </AuthPanel>
+  );
+}
diff --git a/src/page/auth/register.tsx b/src/page/auth/register.tsx
new file mode 100644
index 0000000..8ea532d
--- /dev/null
+++ b/src/page/auth/register.tsx
@@ -0,0 +1,104 @@
+import { useState, type FormEvent } from "react";
+import { Link, useNavigate } from "react-router";
+
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { AuthHeader, AuthPanel } from "./layout";
+import {
+  CaptchaField,
+  FormMessage,
+  PasswordInput,
+  TextField,
+} from "./components";
+import { encryptPassword, fieldValue, getErrorMessage, passwordValue } from "./utils";
+
+export default function RegisterPage() {
+  const navigate = useNavigate();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const [publicKey, setPublicKey] = useState("");
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+    const password = passwordValue(form, "password");
+    const confirmPassword = passwordValue(form, "confirmPassword");
+
+    if (password !== confirmPassword) {
+      setError("Passwords do not match.");
+      setSubmitting(false);
+      return;
+    }
+
+    try {
+      if (!publicKey) {
+        throw new Error("Captcha is not ready. Please refresh it and try again.");
+      }
+
+      await client.authRegister({
+        username: fieldValue(form, "username"),
+        email: fieldValue(form, "email"),
+        password: encryptPassword(publicKey, password),
+        captcha: fieldValue(form, "captcha"),
+      });
+      navigate("/auth/login");
+    } catch (requestError) {
+      setError(getErrorMessage(requestError));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <AuthPanel>
+      <AuthHeader description="Please enter your details to sign up." title="Create account" />
+
+      <form className="relative space-y-4 mt-10" onSubmit={(event) => void handleSubmit(event)}>
+        <TextField id="username" label="Username" name="username" placeholder="Enter your username..." />
+        <TextField
+          id="email"
+          label="E-Mail Address"
+          name="email"
+          placeholder="Enter your email..."
+          type="email"
+        />
+
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold text-zinc-950" htmlFor="password">
+            Password
+          </Label>
+          <PasswordInput id="password" name="password" placeholder="Enter your password..." />
+        </div>
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold text-zinc-950" htmlFor="confirmPassword">
+            Confirm Password
+          </Label>
+          <PasswordInput id="confirmPassword" name="confirmPassword" placeholder="Enter your password again..." />
+        </div>
+
+        <CaptchaField onPublicKey={setPublicKey} />
+
+        {error && <FormMessage tone="error">{error}</FormMessage>}
+
+        <Button
+          className="h-11 w-full rounded-lg bg-zinc-950 text-base text-white shadow-inner shadow-white/10 hover:bg-zinc-800"
+          disabled={submitting}
+          type="submit"
+        >
+          {submitting ? "Please wait..." : "Sign up"}
+        </Button>
+      </form>
+
+      <footer className="mt-6 text-center text-base text-zinc-500">
+        Already have an account?{" "}
+        <Link className="font-semibold text-zinc-950" to="/auth/login">
+          Sign In
+        </Link>
+      </footer>
+    </AuthPanel>
+  );
+}
diff --git a/src/page/auth/reset-password.tsx b/src/page/auth/reset-password.tsx
new file mode 100644
index 0000000..b6b3294
--- /dev/null
+++ b/src/page/auth/reset-password.tsx
@@ -0,0 +1,71 @@
+import { useState, type FormEvent } from "react";
+import { Link, useNavigate, useSearchParams } from "react-router";
+
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { AuthHeader, AuthPanel } from "./layout";
+import { FormMessage, PasswordInput, TextField } from "./components";
+import { fieldValue, getErrorMessage, passwordValue } from "./utils";
+
+export default function ResetPasswordPage() {
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+
+    try {
+      await client.authResetPasswordVerify({
+        token: fieldValue(form, "token") || searchParams.get("token") || "",
+        password: passwordValue(form, "password"),
+      });
+      navigate("/auth/login");
+    } catch (requestError) {
+      setError(getErrorMessage(requestError));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <AuthPanel>
+      <AuthHeader description="Choose a new password for your account." title="Reset password" />
+
+      <form className="relative mt-6 space-y-4" onSubmit={(event) => void handleSubmit(event)}>
+        {!searchParams.get("token") && (
+          <TextField id="token" label="Reset Token" name="token" placeholder="Enter your reset token..." />
+        )}
+
+        <div className="space-y-2">
+          <Label className="text-sm font-semibold text-zinc-950" htmlFor="password">
+            Password
+          </Label>
+          <PasswordInput id="password" name="password" placeholder="Enter your password..." />
+        </div>
+
+        {error && <FormMessage tone="error">{error}</FormMessage>}
+
+        <Button
+          className="h-11 w-full rounded-lg bg-zinc-950 text-base text-white shadow-inner shadow-white/10 hover:bg-zinc-800"
+          disabled={submitting}
+          type="submit"
+        >
+          {submitting ? "Please wait..." : "Reset password"}
+        </Button>
+      </form>
+
+      <footer className="mt-6 text-center text-base text-zinc-500">
+        <Link className="font-semibold text-zinc-950" to="/auth/login">
+          Back to sign in
+        </Link>
+      </footer>
+    </AuthPanel>
+  );
+}
diff --git a/src/page/auth/utils.ts b/src/page/auth/utils.ts
new file mode 100644
index 0000000..bf74b27
--- /dev/null
+++ b/src/page/auth/utils.ts
@@ -0,0 +1,183 @@
+export function getErrorMessage(error: unknown) {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "response" in error &&
+    typeof error.response === "object" &&
+    error.response !== null &&
+    "data" in error.response
+  ) {
+    const data = error.response.data;
+    if (typeof data === "string") {
+      return data;
+    }
+    if (
+      typeof data === "object" &&
+      data !== null &&
+      "message" in data &&
+      typeof data.message === "string"
+    ) {
+      return data.message;
+    }
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return "Request failed. Please try again.";
+}
+
+export function fieldValue(form: FormData, name: string) {
+  return String(form.get(name) ?? "").trim();
+}
+
+export function passwordValue(form: FormData, name: string) {
+  return String(form.get(name) ?? "");
+}
+
+type DerReader = {
+  bytes: Uint8Array;
+  offset: number;
+};
+
+function readLength(reader: DerReader) {
+  const first = reader.bytes[reader.offset++];
+  if (first < 0x80) {
+    return first;
+  }
+
+  const byteCount = first & 0x7f;
+  let length = 0;
+  for (let index = 0; index < byteCount; index += 1) {
+    length = (length << 8) | reader.bytes[reader.offset++];
+  }
+  return length;
+}
+
+function readValue(reader: DerReader, tag: number) {
+  if (reader.bytes[reader.offset++] !== tag) {
+    throw new Error("Invalid RSA public key.");
+  }
+
+  const length = readLength(reader);
+  const value = reader.bytes.slice(reader.offset, reader.offset + length);
+  reader.offset += length;
+  return value;
+}
+
+function readSequence(reader: DerReader) {
+  const value = readValue(reader, 0x30);
+  return { bytes: value, offset: 0 };
+}
+
+function readInteger(reader: DerReader) {
+  let value = readValue(reader, 0x02);
+  while (value.length > 1 && value[0] === 0) {
+    value = value.slice(1);
+  }
+  return value;
+}
+
+function pemToDer(publicKey: string) {
+  const base64 = publicKey
+    .replace(/-----BEGIN [^-]+-----/g, "")
+    .replace(/-----END [^-]+-----/g, "")
+    .replace(/\s/g, "");
+  const binary = atob(base64);
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+
+function parseRsaPublicKey(publicKey: string) {
+  const topLevel = readSequence({ bytes: pemToDer(publicKey), offset: 0 });
+
+  if (topLevel.bytes[topLevel.offset] === 0x02) {
+    return {
+      modulus: readInteger(topLevel),
+      exponent: readInteger(topLevel),
+    };
+  }
+
+  readSequence(topLevel);
+  const bitString = readValue(topLevel, 0x03);
+  const nestedKey = bitString.slice(1);
+  const nested = readSequence({ bytes: nestedKey, offset: 0 });
+  return {
+    modulus: readInteger(nested),
+    exponent: readInteger(nested),
+  };
+}
+
+function bytesToBigInt(bytes: Uint8Array) {
+  return BigInt(`0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`);
+}
+
+function bigIntToBytes(value: bigint, length: number) {
+  const hex = value.toString(16).padStart(length * 2, "0");
+  const bytes = new Uint8Array(length);
+  for (let index = 0; index < length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function modPow(base: bigint, exponent: bigint, modulus: bigint) {
+  let result = 1n;
+  let power = base % modulus;
+  let exp = exponent;
+
+  while (exp > 0n) {
+    if (exp % 2n === 1n) {
+      result = (result * power) % modulus;
+    }
+    exp /= 2n;
+    power = (power * power) % modulus;
+  }
+
+  return result;
+}
+
+function randomNonZeroBytes(length: number) {
+  const bytes = new Uint8Array(length);
+  for (let index = 0; index < length; index += 1) {
+    let value = 0;
+    while (value === 0) {
+      value = crypto.getRandomValues(new Uint8Array(1))[0];
+    }
+    bytes[index] = value;
+  }
+  return bytes;
+}
+
+function bytesToBase64(bytes: Uint8Array) {
+  let binary = "";
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary);
+}
+
+export function encryptPassword(publicKey: string, password: string) {
+  const { modulus, exponent } = parseRsaPublicKey(publicKey);
+  const keySize = modulus.length;
+  const message = new TextEncoder().encode(password);
+
+  if (message.length > keySize - 11) {
+    throw new Error("Password is too long.");
+  }
+
+  const padded = new Uint8Array(keySize);
+  padded[0] = 0;
+  padded[1] = 2;
+  padded.set(randomNonZeroBytes(keySize - message.length - 3), 2);
+  padded[keySize - message.length - 1] = 0;
+  padded.set(message, keySize - message.length);
+
+  const encrypted = modPow(
+    bytesToBigInt(padded),
+    bytesToBigInt(exponent),
+    bytesToBigInt(modulus),
+  );
+
+  return bytesToBase64(bigIntToBytes(encrypted, keySize));
+}
diff --git a/src/page/me/chat-conversation.tsx b/src/page/me/chat-conversation.tsx
new file mode 100644
index 0000000..6b6e3de
--- /dev/null
+++ b/src/page/me/chat-conversation.tsx
@@ -0,0 +1,607 @@
+import { useState, useEffect, useCallback, useRef, useMemo } from "react";
+import { useParams, useNavigate, useLocation } from "react-router";
+import { ArrowLeft, Sparkles } from "lucide-react";
+import { motion, AnimatePresence } from "motion/react";
+import { client } from "@/client";
+import {
+  PromptInput,
+  PromptInputBody,
+  PromptInputTextarea,
+  PromptInputSubmit,
+  PromptInputFooter,
+  PromptInputTools,
+  PromptInputProvider,
+  usePromptInputController,
+} from "@/components/ai-elements/prompt-input";
+import { ModelSelectorPopover } from "@/page/workspace/workplan/chat/model-selector-popover";
+import { MessageBubble } from "@/page/workspace/workplan/chat/message-bubble";
+import { StreamingView } from "@/page/workspace/workplan/chat/streaming-view";
+import type {
+  Message,
+  Conversation,
+  StreamingState,
+} from "@/page/workspace/workplan/chat/types";
+import { EMPTY_STREAM } from "@/page/workspace/workplan/chat/types";
+
+// ---- Helpers ----
+
+const formatDateLabel = (date: string) =>
+  new Date(date).toLocaleDateString([], {
+    month: "long",
+    day: "numeric",
+    year: "numeric",
+  });
+
+function parseSSELine(line: string): Record<string, unknown> | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("data: ")) return null;
+  try {
+    return JSON.parse(trimmed.slice(6));
+  } catch {
+    return null;
+  }
+}
+
+function drainSSEBuffer(buffer: string): {
+  chunks: Record<string, unknown>[];
+  remainder: string;
+} {
+  const lines = buffer.split("\n");
+  const remainder = lines.pop() ?? "";
+  const chunks: Record<string, unknown>[] = [];
+  for (const line of lines) {
+    const parsed = parseSSELine(line);
+    if (parsed) chunks.push(parsed);
+  }
+  return { chunks, remainder };
+}
+
+function makeUserMessage(text: string, conversationId: string): Message {
+  return {
+    id: crypto.randomUUID(),
+    conversation_id: conversationId,
+    role: "user",
+    content: text,
+    content_type: "text",
+    created_at: new Date().toISOString(),
+  };
+}
+
+function makeAssistantMessage(
+  id: string,
+  content: string,
+  conversationId: string,
+): Message {
+  return {
+    id,
+    conversation_id: conversationId,
+    role: "assistant",
+    content,
+    content_type: "text",
+    created_at: new Date().toISOString(),
+  };
+}
+
+function safeStringify(v: unknown): string | undefined {
+  if (typeof v === "string") return v;
+  if (v == null) return undefined;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+// ---- Main component ----
+
+export default function MeChatConversationPage() {
+  const { conversationId = "" } = useParams();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const prefill = (location.state as { prefill?: string } | null)?.prefill;
+
+  const [conversation, setConversation] = useState<Conversation | null>(null);
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [stream, setStream] = useState<StreamingState>(EMPTY_STREAM);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const sendingRef = useRef(false);
+
+  const [sending, setSending] = useState(false);
+  const [modelProvider, setModelProvider] = useState<string>("");
+  const setSendingBoth = useCallback((v: boolean) => {
+    sendingRef.current = v;
+    setSending(v);
+  }, []);
+
+  // ---- Data fetching ----
+
+  const loadData = useCallback(async () => {
+    if (!conversationId) return;
+    try {
+      const [convRes, msgRes] = await Promise.all([
+        client.agentGetConversation(conversationId),
+        client.agentListMessages(conversationId, { limit: 100 }),
+      ]);
+      setConversation(convRes.data);
+      setMessages(msgRes.data as unknown as Message[]);
+      requestAnimationFrame(() => {
+        scrollRef.current?.scrollTo({
+          top: scrollRef.current.scrollHeight,
+          behavior: "instant",
+        });
+      });
+    } catch {
+      // Non-critical.
+    }
+  }, [conversationId]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  // ---- Auto-scroll ----
+
+  const scrollToBottom = useCallback(() => {
+    requestAnimationFrame(() => {
+      scrollRef.current?.scrollTo({
+        top: scrollRef.current.scrollHeight,
+        behavior: "smooth",
+      });
+    });
+  }, []);
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [messages, stream, scrollToBottom]);
+
+  // ---- SSE stream processing ----
+
+  function reduceStreamChunk(
+    prev: StreamingState,
+    chunk: Record<string, unknown>,
+  ): {
+    next: StreamingState;
+    addAssistantMessage?: { id: string; content: string };
+    reloadData?: boolean;
+  } {
+    const next: StreamingState = {
+      ...prev,
+      toolCalls: prev.toolCalls.map((tc) => ({ ...tc })),
+    };
+
+    switch (chunk.type) {
+      case "phase_change":
+        next.phase = chunk.phase as StreamingState["phase"];
+        return { next };
+      case "thinking":
+        if (typeof chunk.content === "string") {
+          next.phase = "think";
+          next.thinkText += chunk.content;
+        }
+        return { next };
+      case "delta":
+        if (typeof chunk.content === "string") {
+          next.phase = "answer";
+          next.answerText += chunk.content;
+        }
+        return { next };
+      case "tool_call_started": {
+        next.phase = "act";
+        const tc = {
+          toolCallId: chunk.tool_call_id as string,
+          toolName: chunk.tool_name as string,
+          arguments: chunk.arguments as string,
+        };
+        if (!next.toolCalls.some((t) => t.toolCallId === tc.toolCallId)) {
+          next.toolCalls = [...next.toolCalls, tc];
+        }
+        return { next };
+      }
+      case "tool_call_finished": {
+        next.phase = "act";
+        const idx = next.toolCalls.findIndex(
+          (t) => t.toolCallId === (chunk.tool_call_id as string),
+        );
+        if (idx !== -1) {
+          const updated = { ...next.toolCalls[idx] };
+          updated.output = safeStringify(chunk.output);
+          updated.error = chunk.error as string | null;
+          next.toolCalls = [
+            ...next.toolCalls.slice(0, idx),
+            updated,
+            ...next.toolCalls.slice(idx + 1),
+          ];
+        }
+        return { next };
+      }
+      case "done": {
+        const output = safeStringify(chunk.output) ?? next.answerText;
+        const messageId =
+          (chunk.message_id as string) || crypto.randomUUID();
+        return {
+          next: EMPTY_STREAM,
+          addAssistantMessage: { id: messageId, content: output },
+          reloadData: !!chunk.message_id,
+        };
+      }
+      case "title_updated":
+        return { next, reloadData: true };
+      case "subagent_started":
+        return {
+          next: {
+            ...next,
+            phase: "act" as StreamingState["phase"],
+            toolCalls: [
+              ...next.toolCalls,
+              {
+                toolCallId: chunk.subagent_id as string,
+                toolName: `Subagent: ${chunk.role || "specialist"}`,
+                arguments: chunk.task as string,
+              },
+            ],
+          },
+        };
+      case "subagent_completed": {
+        next.phase = "act";
+        const saIdx = next.toolCalls.findIndex(
+          (t) => t.toolCallId === (chunk.subagent_id as string),
+        );
+        if (saIdx !== -1) {
+          const updated = { ...next.toolCalls[saIdx] };
+          updated.output = safeStringify(chunk.output);
+          next.toolCalls = [
+            ...next.toolCalls.slice(0, saIdx),
+            updated,
+            ...next.toolCalls.slice(saIdx + 1),
+          ];
+        }
+        return { next };
+      }
+      case "subagent_failed":
+      case "error":
+        return {
+          next: EMPTY_STREAM,
+          addAssistantMessage: {
+            id: crypto.randomUUID(),
+            content: `Error: ${chunk.error || "Stream error"}`,
+          },
+        };
+      default:
+        return { next };
+    }
+  }
+
+  const processChunk = useCallback(
+    (chunk: Record<string, unknown>) => {
+      setStream((prev) => {
+        const { next, addAssistantMessage, reloadData } = reduceStreamChunk(
+          prev,
+          chunk,
+        );
+        if (addAssistantMessage && !reloadData) {
+          const msg = makeAssistantMessage(
+            addAssistantMessage.id,
+            addAssistantMessage.content,
+            conversationId,
+          );
+          queueMicrotask(() => {
+            setMessages((prevMessages) => [...prevMessages, msg]);
+          });
+        }
+        if (reloadData) {
+          queueMicrotask(() => loadData());
+        }
+        return next;
+      });
+    },
+    [conversationId, loadData],
+  );
+
+  // ---- Send message ----
+
+  const sendMessage = useCallback(
+    async (text: string) => {
+      if (!text.trim() || !conversation || sendingRef.current) return;
+
+      setSendingBoth(true);
+      setStream(EMPTY_STREAM);
+
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      setMessages((prev) => [
+        ...prev,
+        makeUserMessage(text, conversationId),
+      ]);
+
+      try {
+        const response = await fetch(
+          `/api/v1/agent/conversations/${conversationId}/stream`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({
+              session_id: conversation.session_id,
+              conversation_id: conversationId,
+              input: text,
+              stream: true,
+            }),
+            signal: controller.signal,
+          },
+        );
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const reader = response.body?.getReader();
+        if (!reader) throw new Error("No response body");
+
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const { chunks, remainder } = drainSSEBuffer(buffer);
+          buffer = remainder;
+          for (const chunk of chunks) {
+            processChunk(chunk);
+          }
+        }
+
+        if (buffer.trim()) {
+          const { chunks } = drainSSEBuffer(buffer + "\n");
+          for (const chunk of chunks) {
+            processChunk(chunk);
+          }
+        }
+      } catch (err: unknown) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        setMessages((prev) => [
+          ...prev,
+          makeAssistantMessage(
+            crypto.randomUUID(),
+            err instanceof Error ? `Error: ${err.message}` : "Request failed",
+            conversationId,
+          ),
+        ]);
+      } finally {
+        setSendingBoth(false);
+        abortRef.current = null;
+      }
+    },
+    [conversation, conversationId, processChunk, setSendingBoth],
+  );
+
+  // ---- Prefill ----
+
+  const prefilledRef = useRef(false);
+  useEffect(() => {
+    if (prefill && !prefilledRef.current && conversation && !sending) {
+      prefilledRef.current = true;
+      const timer = setTimeout(() => {
+        sendMessage(prefill);
+      }, 100);
+      return () => clearTimeout(timer);
+    }
+  }, [prefill, conversation, sending, sendMessage]);
+
+  // ---- Stop ----
+
+  const handleStop = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+
+  // ---- Computed ----
+
+  const messageGroups = useMemo(() => {
+    const groups: { date: string; messages: Message[] }[] = [];
+    for (const msg of messages) {
+      const ds = formatDateLabel(msg.created_at);
+      const last = groups[groups.length - 1];
+      if (last?.date === ds) {
+        last.messages.push(msg);
+      } else {
+        groups.push({ date: ds, messages: [msg] });
+      }
+    }
+    return groups;
+  }, [messages]);
+
+  const hasActiveStream = sending || stream.phase !== "idle";
+  const allMessages = useMemo(
+    () => messageGroups.flatMap((g) => g.messages),
+    [messageGroups],
+  );
+
+  return (
+    <PromptInputProvider>
+      <div className="flex h-full flex-col overflow-hidden bg-background">
+        {/* Header */}
+        <header className="flex h-12 shrink-0 items-center gap-2.5 border-b border-border/60 bg-card/50 px-4 backdrop-blur-sm">
+          <motion.button
+            type="button"
+            whileHover={{ scale: 1.05, x: -1 }}
+            whileTap={{ scale: 0.92 }}
+            className="inline-flex size-8 cursor-pointer items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            onClick={() => navigate("/me/chat")}
+            aria-label="Back to chat list"
+          >
+            <ArrowLeft className="size-4" aria-hidden="true" />
+          </motion.button>
+
+          <div className="flex min-w-0 flex-1 items-center gap-2">
+            <div className="grid size-6 place-items-center rounded-md bg-primary/10">
+              <Sparkles className="size-3 text-primary/70" />
+            </div>
+            <h1 className="truncate text-sm font-semibold text-foreground">
+              {conversation?.title ?? "Loading..."}
+            </h1>
+          </div>
+        </header>
+
+        {/* Messages */}
+        <div
+          className="scrollbar-none relative min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-6"
+          ref={scrollRef}
+          role="log"
+          aria-label="Conversation messages"
+          aria-live="polite"
+        >
+          <AnimatePresence>
+            {messageGroups.length === 0 && !hasActiveStream && (
+              <motion.div
+                initial={{ opacity: 0, scale: 0.96 }}
+                animate={{ opacity: 1, scale: 1 }}
+                exit={{ opacity: 0, scale: 0.96 }}
+                transition={{ duration: 0.3, ease: "easeOut" }}
+                className="flex h-full items-center justify-center"
+              >
+                <div className="text-center">
+                  <div className="mx-auto grid size-16 place-items-center rounded-2xl bg-gradient-to-br from-primary/10 to-primary/[0.02] ring-1 ring-primary/10 shadow-sm">
+                    <Sparkles className="size-7 text-primary/30" />
+                  </div>
+                  <p className="mt-4 text-sm font-medium text-muted-foreground/60">
+                    Start a conversation
+                  </p>
+                  <p className="mt-1 text-xs text-muted-foreground/35">
+                    Type a message below to begin
+                  </p>
+                </div>
+              </motion.div>
+            )}
+          </AnimatePresence>
+
+          <div className="mx-auto max-w-3xl space-y-6">
+            {messageGroups.map((group) => (
+              <div key={group.date}>
+                <div className="my-8 flex items-center justify-center gap-3">
+                  <div className="h-px w-12 bg-gradient-to-r from-transparent to-border/50" />
+                  <span className="rounded-full bg-muted/50 px-3 py-1 text-[11px] font-medium text-muted-foreground/60 shadow-sm">
+                    {group.date}
+                  </span>
+                  <div className="h-px w-12 bg-gradient-to-l from-transparent to-border/50" />
+                </div>
+
+                <div className="space-y-4">
+                  {group.messages.map((msg) => (
+                    <motion.div
+                      key={msg.id}
+                      data-msg-index={allMessages.indexOf(msg)}
+                      data-msg-role={msg.role}
+                      initial={{ opacity: 0, y: 10 }}
+                      animate={{ opacity: 1, y: 0 }}
+                      transition={{ duration: 0.25, ease: "easeOut" }}
+                    >
+                      <MessageBubble msg={msg} modelProvider={modelProvider} />
+                    </motion.div>
+                  ))}
+                </div>
+              </div>
+            ))}
+
+            <AnimatePresence>
+              {hasActiveStream && (
+                <motion.div
+                  key="streaming"
+                  initial={{ opacity: 0, y: 10 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  exit={{ opacity: 0, y: 6 }}
+                  transition={{ duration: 0.2 }}
+                >
+                  <StreamingView stream={stream} modelProvider={modelProvider} />
+                </motion.div>
+              )}
+            </AnimatePresence>
+          </div>
+        </div>
+
+        {/* Composer */}
+        <ChatComposer
+          conversation={conversation}
+          sending={sending}
+          sendMessage={sendMessage}
+          handleStop={handleStop}
+          onModelChange={setModelProvider}
+        />
+      </div>
+    </PromptInputProvider>
+  );
+}
+
+// ---- Composer ----
+
+function ChatComposer({
+  conversation,
+  sending,
+  sendMessage,
+  handleStop,
+  onModelChange,
+}: {
+  conversation: Conversation | null;
+  sending: boolean;
+  sendMessage: (text: string) => Promise<void>;
+  handleStop: () => void;
+  onModelChange: (provider: string) => void;
+}) {
+  const { textInput } = usePromptInputController();
+
+  const handleSubmit = useCallback(
+    (text: string) => {
+      if (text.trim()) {
+        sendMessage(text);
+        textInput.clear();
+      }
+    },
+    [sendMessage, textInput],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.key === "Enter" && !e.shiftKey && !sending) {
+        e.preventDefault();
+        const text = textInput.value;
+        if (text.trim()) {
+          sendMessage(text);
+          textInput.clear();
+        }
+      }
+    },
+    [sendMessage, textInput, sending],
+  );
+
+  return (
+    <footer className="shrink-0 border-t border-border/60 bg-card/70 backdrop-blur-md">
+      <div className="mx-auto max-w-3xl px-4 py-3">
+        <PromptInput globalDrop={false} onSubmit={({ text }) => handleSubmit(text)}>
+          <PromptInputBody>
+            <PromptInputTextarea
+              className="min-h-[48px] max-h-[200px] resize-none rounded-xl border-border/60 bg-muted/40 text-sm shadow-inner transition-colors focus-visible:bg-background focus-visible:ring-1 focus-visible:ring-primary/20"
+              placeholder="Type a message…"
+              onKeyDown={handleKeyDown}
+            />
+          </PromptInputBody>
+          <PromptInputFooter>
+            <PromptInputTools>
+              <ModelSelectorPopover
+                sessionId={conversation?.session_id}
+                onModelChange={(_name, provider) => onModelChange(provider)}
+              />
+            </PromptInputTools>
+            <PromptInputSubmit
+              status={sending ? "streaming" : undefined}
+              onStop={handleStop}
+            />
+          </PromptInputFooter>
+        </PromptInput>
+        <p className="mt-1.5 text-center text-[11px] text-muted-foreground/30">
+          AI responses may be inaccurate. Verify important information.
+        </p>
+      </div>
+    </footer>
+  );
+}
diff --git a/src/page/me/chat-list.tsx b/src/page/me/chat-list.tsx
new file mode 100644
index 0000000..cb735ac
--- /dev/null
+++ b/src/page/me/chat-list.tsx
@@ -0,0 +1,141 @@
+import { useCallback } from "react";
+import { useNavigate } from "react-router";
+import { Plus, Sparkles, Code2, Bug, Lightbulb, Wand2 } from "lucide-react";
+import { motion } from "motion/react";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { usePersonalSessions, ensurePersonalSession } from "./chat/use-personal-sessions";
+
+interface SuggestionCard {
+  title: string;
+  body: string;
+  icon: React.ComponentType<{ className?: string }>;
+  gradient: string;
+}
+
+const SUGGESTIONS: SuggestionCard[] = [
+  {
+    title: "Code Review",
+    body: "Review my pull request for bugs and improvements",
+    icon: Code2,
+    gradient: "from-emerald-500/10 to-emerald-500/[0.02]",
+  },
+  {
+    title: "Debug Help",
+    body: "Help me diagnose this failing test case",
+    icon: Bug,
+    gradient: "from-amber-500/10 to-amber-500/[0.02]",
+  },
+  {
+    title: "Explain Code",
+    body: "Explain how this algorithm works step by step",
+    icon: Lightbulb,
+    gradient: "from-violet-500/10 to-violet-500/[0.02]",
+  },
+  {
+    title: "Refactor",
+    body: "Suggest refactoring for better readability",
+    icon: Wand2,
+    gradient: "from-sky-500/10 to-sky-500/[0.02]",
+  },
+];
+
+export default function MeChatListPage() {
+  const navigate = useNavigate();
+  const { sessionsRef } = usePersonalSessions();
+
+  const startConversation = useCallback(
+    async (title: string, prefillBody?: string) => {
+      try {
+        const sessionId = await ensurePersonalSession(sessionsRef.current);
+        if (!sessionId) return;
+
+        const r = await client.agentCreateConversation(sessionId, { title });
+        navigate(`/me/chat/${r.data.id}`, {
+          state: prefillBody ? { prefill: prefillBody } : undefined,
+        });
+      } catch {
+        // Silently fail.
+      }
+    },
+    [navigate, sessionsRef],
+  );
+
+  const handleNewChat = useCallback(() => {
+    startConversation("New Chat");
+  }, [startConversation]);
+
+  const handleQuickStart = useCallback(
+    (title: string, body: string) => {
+      startConversation(title, body);
+    },
+    [startConversation],
+  );
+
+  return (
+    <div className="flex h-full items-center justify-center px-8">
+      <motion.div
+        initial={{ opacity: 0, y: 20 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4, ease: "easeOut" }}
+        className="max-w-md text-center"
+      >
+        <div className="mx-auto grid size-20 place-items-center rounded-2xl bg-gradient-to-br from-primary/15 to-primary/[0.03] ring-1 ring-primary/10 shadow-sm">
+          <Sparkles className="size-9 text-primary/30" aria-hidden="true" />
+        </div>
+
+        <h1 className="mt-6 text-xl font-bold tracking-tight text-foreground">
+          AI Assistant
+        </h1>
+        <p className="mt-2 text-sm leading-relaxed text-muted-foreground/70">
+          Start a conversation with your personal AI assistant. Ask questions,
+          get code help, discuss ideas, and more.
+        </p>
+
+        <div className="mt-6 flex items-center justify-center gap-3">
+          <motion.div whileHover={{ scale: 1.03 }} whileTap={{ scale: 0.97 }}>
+            <Button
+              className="cursor-pointer shadow-sm"
+              onClick={handleNewChat}
+              size="default"
+              variant="default"
+            >
+              <Plus className="mr-2 size-4" aria-hidden="true" />
+              New Chat
+            </Button>
+          </motion.div>
+        </div>
+
+        <div className="mt-10 grid grid-cols-2 gap-2.5 text-left">
+          {SUGGESTIONS.map((suggestion, i) => {
+            const Icon = suggestion.icon;
+            return (
+              <motion.button
+                key={suggestion.title}
+                initial={{ opacity: 0, y: 12 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ duration: 0.3, delay: 0.1 + i * 0.06 }}
+                whileHover={{ scale: 1.02, transition: { duration: 0.15 } }}
+                whileTap={{ scale: 0.98 }}
+                type="button"
+                className={`group cursor-pointer rounded-xl border border-border/40 bg-gradient-to-br ${suggestion.gradient} px-4 py-3.5 text-left transition-all duration-200 hover:border-border/80 hover:shadow-sm hover:ring-1 hover:ring-primary/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring`}
+                onClick={() => handleQuickStart(suggestion.title, suggestion.body)}
+                aria-label={`${suggestion.title}: ${suggestion.body}`}
+              >
+                <div className="flex items-center gap-2">
+                  <Icon className="size-3.5 text-muted-foreground/50 transition-colors group-hover:text-foreground/70" />
+                  <p className="text-[13px] font-medium text-foreground">
+                    {suggestion.title}
+                  </p>
+                </div>
+                <p className="mt-1.5 text-[11px] leading-relaxed text-muted-foreground/50">
+                  {suggestion.body}
+                </p>
+              </motion.button>
+            );
+          })}
+        </div>
+      </motion.div>
+    </div>
+  );
+}
diff --git a/src/page/me/chat.tsx b/src/page/me/chat.tsx
new file mode 100644
index 0000000..e1448e7
--- /dev/null
+++ b/src/page/me/chat.tsx
@@ -0,0 +1,2 @@
+import MeChatListPage from "./chat-list";
+export default MeChatListPage;
diff --git a/src/page/me/chat/use-personal-sessions.ts b/src/page/me/chat/use-personal-sessions.ts
new file mode 100644
index 0000000..5e52a74
--- /dev/null
+++ b/src/page/me/chat/use-personal-sessions.ts
@@ -0,0 +1,77 @@
+import { useState, useEffect, useRef, useCallback, useMemo } from "react";
+import { client } from "@/client";
+import type { AgentSessionResponse } from "@/client/models/agentSessionResponse";
+
+/**
+ * Load personal agent sessions (wk is null — not tied to any workspace).
+ */
+export function usePersonalSessions() {
+  const [sessions, setSessions] = useState<AgentSessionResponse[]>([]);
+  const [loading, setLoading] = useState(true);
+  const sessionsRef = useRef<AgentSessionResponse[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    client
+      .agentListSessions()
+      .then(({ data }) => {
+        if (!cancelled) {
+          // Only keep sessions without a workspace
+          const personal = data.filter(
+            (s) => s.enabled && (s.wk == null || s.wk === ""),
+          );
+          sessionsRef.current = personal;
+          setSessions(personal);
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const addSession = useCallback((session: AgentSessionResponse) => {
+    setSessions((prev) => {
+      if (prev.some((s) => s.id === session.id)) return prev;
+      return [...prev, session];
+    });
+  }, []);
+
+  /** Set of personal session IDs for fast lookup */
+  const personalSessionIds = useMemo(
+    () => new Set(sessions.map((s) => s.id)),
+    [sessions],
+  );
+
+  return { sessions, loading, sessionsRef, personalSessionIds, addSession };
+}
+
+/** Ensure a personal agent session exists (without workspace), creating one if needed. */
+export async function ensurePersonalSession(
+  existingSessions: AgentSessionResponse[],
+): Promise<string | null> {
+  const personalSession = existingSessions.find(
+    (s) => s.enabled && (s.wk == null || s.wk === ""),
+  );
+  if (personalSession) return personalSession.id;
+
+  try {
+    const modelsRes = await client.aiListModels();
+    const modelVersion = modelsRes.data[0]?.id;
+    if (!modelVersion) return null;
+
+    const res = await client.agentCreateSession({
+      name: "Personal Agent",
+      agent_kind: "chat",
+      model_version: modelVersion,
+      wk: null,
+    });
+    return res.data.id;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/page/me/following.tsx b/src/page/me/following.tsx
new file mode 100644
index 0000000..c24cbc3
--- /dev/null
+++ b/src/page/me/following.tsx
@@ -0,0 +1,114 @@
+import { useState } from "react";
+import { useAuth } from "@/context/auth-context";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Users, UserPlus } from "lucide-react";
+import { Link } from "react-router";
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+
+export default function MeFollowingPage() {
+  const { me } = useAuth();
+  const username = me?.username ?? "";
+  const [tab, setTab] = useState<"followers" | "following">("followers");
+
+  const { data: followers = [], isLoading: loadingFollowers } = useQuery({
+    queryKey: ["me", "followers", username],
+    queryFn: async () => {
+      const res = await client.usersFollowers(username);
+      return res.data;
+    },
+    enabled: Boolean(username),
+    retry: false,
+  });
+
+  const { data: following = [], isLoading: loadingFollowing } = useQuery({
+    queryKey: ["me", "following", username],
+    queryFn: async () => {
+      const res = await client.usersFollowing(username);
+      return res.data;
+    },
+    enabled: Boolean(username),
+    retry: false,
+  });
+
+  const { data: counts } = useQuery({
+    queryKey: ["me", "relation-counts", username],
+    queryFn: async () => {
+      const res = await client.usersRelationCounts(username);
+      return res.data;
+    },
+    enabled: Boolean(username),
+    retry: false,
+  });
+
+  const tabs = [
+    { key: "followers" as const, label: "Followers", count: counts?.followers ?? followers.length },
+    { key: "following" as const, label: "Following", count: counts?.following ?? following.length },
+  ];
+
+  const currentList = tab === "followers" ? followers : following;
+  const isLoading = tab === "followers" ? loadingFollowers : loadingFollowing;
+
+  return (
+    <div className="mx-auto max-w-2xl px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Following</h1>
+
+      {/* Tab switch */}
+      <nav className="mt-6 grid grid-cols-2 gap-1 rounded-xl bg-muted/70 p-1">
+        {tabs.map((t) => (
+          <button
+            className={cn(
+              "flex h-8 items-center justify-center gap-2 rounded-md text-sm font-semibold text-muted-foreground transition-colors hover:text-foreground",
+              tab === t.key && "bg-card text-foreground shadow-sm ring-1 ring-border",
+            )}
+            key={t.key}
+            onClick={() => setTab(t.key)}
+          >
+            {t.label}
+            <span className="font-mono text-xs">{t.count}</span>
+          </button>
+        ))}
+      </nav>
+
+      {/* User list */}
+      <div className="mt-6 space-y-1">
+        {isLoading ? (
+          Array.from({ length: 3 }).map((_, i) => (
+            <div className="h-10 animate-pulse rounded-lg bg-muted" key={i} />
+          ))
+        ) : currentList.length > 0 ? (
+          currentList.map((user) => (
+            <div className="flex items-center gap-3 rounded-lg px-3 py-3 hover:bg-accent/50 transition-colors" key={user.username}>
+              <Link className="flex items-center gap-3 min-w-0 flex-1" to={`/${user.username}`}>
+                <span className={`grid size-8 place-items-center rounded-lg bg-gradient-to-br text-xs font-bold text-white ${workspaceColor(user.username)}`}>
+                  {user.avatar_url ? <img alt="" className="size-full object-cover" src={user.avatar_url} /> : workspaceInitial(user.username)}
+                </span>
+                <div className="min-w-0">
+                  <p className="font-heading font-medium text-foreground">{user.display_name ?? user.username}</p>
+                  <p className="font-mono text-xs text-muted-foreground">@{user.username}</p>
+                </div>
+              </Link>
+              {user.is_following ? (
+                <span className="font-mono text-xs text-muted-foreground">Following</span>
+              ) : (
+                <Button className="rounded-lg text-xs h-7" size="sm" variant="outline">
+                  <UserPlus className="size-3" />
+                  Follow
+                </Button>
+              )}
+            </div>
+          ))
+        ) : (
+          <div className="py-10 text-center">
+            <Users className="mx-auto size-5 text-muted-foreground/30" />
+            <p className="mt-3 text-sm text-muted-foreground">
+              {tab === "followers" ? "No followers yet" : "Not following anyone yet"}
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/me/notifications.tsx b/src/page/me/notifications.tsx
new file mode 100644
index 0000000..075eb5b
--- /dev/null
+++ b/src/page/me/notifications.tsx
@@ -0,0 +1,93 @@
+import { Bell, Check, ChevronRight } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { client } from "@/client";
+import { useQuery } from "@tanstack/react-query";
+import { useAuth } from "@/context/auth-context";
+
+export default function MeNotificationsPage() {
+  const { me } = useAuth();
+  const unreadCount = me?.has_unread_notifications ?? 0;
+
+  const { data: notifications, isLoading } = useQuery({
+    queryKey: ["user", "notifications"],
+    queryFn: async () => {
+      const res = await client.userListNotifications();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  return (
+    <div className="mx-auto max-w-2xl px-8 py-10">
+      <div className="flex items-start justify-between">
+        <div>
+          <h1 className="text-xl font-heading font-bold text-foreground">Notifications</h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            {unreadCount > 0 ? `${unreadCount} unread` : "All caught up"}
+          </p>
+        </div>
+        {unreadCount > 0 && (
+          <Button className="rounded-lg border-border text-muted-foreground hover:text-foreground" variant="outline">
+            <Check className="size-4" />
+            Mark all read
+          </Button>
+        )}
+      </div>
+
+      <div className="mt-6 space-y-1">
+        {isLoading ? (
+          Array.from({ length: 3 }).map((_, i) => (
+            <div className="h-16 animate-pulse rounded-lg bg-muted" key={i} />
+          ))
+        ) : (notifications ?? []).length > 0 ? (
+          notifications!.map((notif) => (
+            <div
+              className="flex items-start gap-3 rounded-lg px-4 py-4 transition-colors hover:bg-accent/50 cursor-pointer"
+              key={notif.id}
+            >
+              <span
+                className={`mt-1 size-2 rounded-full shrink-0 ${
+                  notif.read_at ? "bg-muted-foreground/30" : "bg-primary"
+                }`}
+              />
+              <div className="min-w-0 flex-1">
+                <p
+                  className={`font-heading font-medium text-sm ${
+                    notif.read_at ? "text-muted-foreground" : "text-foreground"
+                  }`}
+                >
+                  {notif.title}
+                </p>
+                <p className="text-xs text-muted-foreground">{notif.body}</p>
+              </div>
+              <span className="font-mono text-xs text-muted-foreground shrink-0 flex items-center gap-1">
+                {formatTime(notif.created_at)}
+                <ChevronRight className="size-3" />
+              </span>
+            </div>
+          ))
+        ) : (
+          <div className="mt-16 text-center">
+            <Bell className="mx-auto size-6 text-muted-foreground/30" />
+            <p className="mt-4 text-sm text-muted-foreground">No notifications yet</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function formatTime(dateStr: string): string {
+  const date = new Date(dateStr);
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+  const days = Math.floor(diff / 86400000);
+
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  if (hours < 24) return `${hours}h ago`;
+  if (days < 7) return `${days}d ago`;
+  return date.toLocaleDateString();
+}
diff --git a/src/page/me/overview/activity.tsx b/src/page/me/overview/activity.tsx
new file mode 100644
index 0000000..f7c7efd
--- /dev/null
+++ b/src/page/me/overview/activity.tsx
@@ -0,0 +1,118 @@
+import { Link } from "react-router";
+import { ChevronRight, Clock, Lock, Activity, Users } from "lucide-react";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+
+export function WorkspaceList({ workspaces }: { workspaces: { name: string; avatar_url: string; description: string; owner: boolean }[] | undefined }) {
+  return (
+    <section>
+      <div className="flex items-center justify-between">
+        <h2 className="font-mono text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+          Workspaces
+        </h2>
+        <Link
+          className="flex items-center gap-1 font-mono text-xs text-muted-foreground hover:text-foreground transition-colors"
+          to="/me/repos"
+        >
+          View all <ChevronRight className="size-3" />
+        </Link>
+      </div>
+      <div className="mt-4 space-y-4">
+        {(workspaces ?? []).slice(0, 5).map((ws) => (
+          <Link
+            className="group flex items-center gap-3 rounded-lg -mx-2 px-2 py-2 transition-colors hover:bg-accent/50"
+            key={ws.name}
+            to={`/${ws.name}/repos`}
+          >
+            <span
+              className={`grid size-7 place-items-center rounded-lg bg-gradient-to-br text-xs font-bold text-white ${workspaceColor(ws.name)}`}
+            >
+              {ws.avatar_url ? <img alt="" className="size-full object-cover" src={ws.avatar_url} /> : workspaceInitial(ws.name)}
+            </span>
+            <div className="min-w-0 flex-1">
+              <div className="flex items-center gap-1.5">
+                <span className="font-heading font-semibold text-foreground truncate">{ws.name}</span>
+                {ws.owner && <Lock className="size-3 text-muted-foreground" />}
+              </div>
+              <p className="text-xs text-muted-foreground truncate">{ws.description}</p>
+            </div>
+          </Link>
+        ))}
+        {(workspaces ?? []).length === 0 && (
+          <p className="py-4 text-center text-sm text-muted-foreground">No workspaces yet</p>
+        )}
+      </div>
+    </section>
+  );
+}
+
+export function ActivityFeed({ relationCounts }: { relationCounts: { followers: number; following: number } | undefined }) {
+  const { data: joinApplies } = useQuery({
+    queryKey: ["workspace", "join-applies"],
+    queryFn: async () => {
+      const res = await client.workspaceMyJoinApplies();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const pending = (joinApplies ?? []).filter((a) => a.status === "pending");
+
+  return (
+    <section>
+      <h2 className="font-mono text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+        Recent activity
+      </h2>
+      <div className="mt-4 divide-y divide-border">
+        {pending.slice(0, 2).map((apply) => (
+          <div className="flex items-start gap-3 py-3" key={`${apply.workspace_name}-${apply.username}`}>
+            <span
+              className={`grid size-6 place-items-center rounded-md bg-gradient-to-br text-xs font-bold text-white ${workspaceColor(apply.workspace_name)}`}
+            >
+              {workspaceInitial(apply.workspace_name)}
+            </span>
+            <div className="min-w-0 flex-1">
+              <p className="font-heading font-medium text-foreground">
+                Requested to join {apply.workspace_name}
+              </p>
+              <p className="font-mono text-xs text-muted-foreground">
+                <Clock className="inline size-3 mr-1" />
+                {new Date(apply.updated_at).toLocaleDateString("en-US", { month: "short", day: "numeric" })}
+              </p>
+            </div>
+            <span className="font-mono text-[10px] uppercase tracking-wider text-amber-600 rounded-md border border-amber-200 bg-amber-50 px-2 py-0.5">
+              Pending
+            </span>
+          </div>
+        ))}
+        {pending.length === 0 && (
+          <div className="flex items-start gap-3 py-3">
+            <Activity className="size-4 text-muted-foreground mt-0.5" />
+            <div>
+              <p className="font-heading font-medium text-foreground">Signed in</p>
+              <p className="font-mono text-xs text-muted-foreground">Today</p>
+            </div>
+          </div>
+        )}
+      </div>
+
+      {relationCounts && (
+        <div className="mt-6">
+          <Link
+            className="group flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-3 transition-colors hover:border-primary/20"
+            to="/me/following"
+          >
+            <Users className="size-4 text-muted-foreground group-hover:text-primary transition-colors" />
+            <div className="flex-1">
+              <p className="font-heading font-medium text-foreground">
+                {relationCounts.followers} followers · {relationCounts.following} following
+              </p>
+            </div>
+            <ChevronRight className="size-4 text-muted-foreground" />
+          </Link>
+        </div>
+      )}
+    </section>
+  );
+}
\ No newline at end of file
diff --git a/src/page/me/overview/heatmap.tsx b/src/page/me/overview/heatmap.tsx
new file mode 100644
index 0000000..180353f
--- /dev/null
+++ b/src/page/me/overview/heatmap.tsx
@@ -0,0 +1,55 @@
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import type { ContributionHeatmapItem } from "@/client/models/contributionHeatmapItem";
+
+export function ContributionHeatmap() {
+  const { data: heatmap } = useQuery({
+    queryKey: ["me", "heatmap"],
+    queryFn: async () => {
+      const res = await client.userContributionHeatmap();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const total = heatmap?.total_contributions ?? 0;
+  const items = heatmap?.heatmap ?? [];
+
+  return (
+    <section className="mt-10">
+      <div className="flex items-center justify-between">
+        <h2 className="font-heading font-semibold text-sm text-foreground">
+          {total} contributions
+        </h2>
+        {heatmap && (
+          <p className="font-mono text-xs text-muted-foreground">
+            {heatmap.start_date} — {heatmap.end_date}
+          </p>
+        )}
+      </div>
+      <div className="mt-4 flex flex-wrap gap-[3px]">
+        {items.length > 0
+          ? items.map((item: ContributionHeatmapItem) => {
+              const intensity = Math.min(item.count / 5, 1);
+              return (
+                <span
+                  className="size-[10px] rounded-sm"
+                  key={item.date}
+                  style={{
+                    backgroundColor: item.count === 0
+                      ? "var(--color-muted)"
+                      : `oklch(${0.35 + intensity * 0.35} ${0.05 + intensity * 0.19} 290)`,
+                  }}
+                />
+              );
+            })
+          : Array.from({ length: 154 }).map((_, i) => (
+              <span
+                className={`size-[10px] rounded-sm ${i > 128 && i % 4 !== 0 ? "bg-primary/60" : "bg-muted"}`}
+                key={i}
+              />
+            ))}
+      </div>
+    </section>
+  );
+}
\ No newline at end of file
diff --git a/src/page/me/overview/index.tsx b/src/page/me/overview/index.tsx
new file mode 100644
index 0000000..d1b0cbb
--- /dev/null
+++ b/src/page/me/overview/index.tsx
@@ -0,0 +1,121 @@
+import { useAuth } from "@/context/auth-context";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { CalendarDays, GitFork, Folder, Star, Users } from "lucide-react";
+import { Link } from "react-router";
+import { workspaceInitial } from "@/components/shell/shared";
+import { ContributionHeatmap } from "./heatmap";
+import { WorkspaceList, ActivityFeed } from "./activity";
+
+export default function MeOverviewPage() {
+  const { me } = useAuth();
+  const username = me?.username ?? "";
+
+  const { data: summary } = useQuery({
+    queryKey: ["me", "summary", username],
+    queryFn: async () => {
+      const res = await client.usersUserSummary(username);
+      return res.data;
+    },
+    enabled: Boolean(username),
+    retry: false,
+  });
+
+  const { data: workspaces } = useQuery({
+    queryKey: ["workspace", "my"],
+    queryFn: async () => {
+      const res = await client.workspaceMyWorkspaces();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const { data: relationCounts } = useQuery({
+    queryKey: ["me", "relations", username],
+    queryFn: async () => {
+      const res = await client.usersRelationCounts(username);
+      return res.data;
+    },
+    enabled: Boolean(username),
+    retry: false,
+  });
+
+  const displayName = summary?.display_name ?? me?.display_name ?? username;
+  const avatarUrl = summary?.avatar_url ?? me?.avatar_url;
+  const createdAt = summary?.created_at;
+  const websiteUrl = summary?.website_url;
+
+  const joinDate = createdAt
+    ? new Date(createdAt).toLocaleDateString("en-US", { month: "short", year: "numeric" })
+    : "";
+
+  return (
+    <div className="mx-auto max-w-4xl px-8 py-10">
+      {/* Profile header */}
+      <div className="flex items-center gap-5">
+        <div className="grid size-16 place-items-center overflow-hidden rounded-xl bg-gradient-to-br text-xl font-heading font-bold text-white ring-1 ring-black/5 shadow-sm">
+          {avatarUrl ? (
+            <img alt="" className="size-full object-cover" src={avatarUrl} />
+          ) : (
+            workspaceInitial(displayName)
+          )}
+        </div>
+        <div className="min-w-0">
+          <h1 className="text-xl font-heading font-bold text-foreground truncate">{displayName}</h1>
+          <p className="font-mono text-sm text-muted-foreground">@{username}</p>
+          <div className="mt-3 flex items-center gap-3">
+            {joinDate && (
+              <span className="inline-flex items-center gap-1.5 rounded-md border border-border px-2.5 py-1 text-xs text-muted-foreground">
+                <CalendarDays className="size-3.5" />
+                Joined {joinDate}
+              </span>
+            )}
+            {websiteUrl && (
+              <a
+                className="inline-flex items-center gap-1.5 rounded-md border border-border px-2.5 py-1 text-xs text-primary hover:border-primary/30 transition-colors"
+                href={websiteUrl}
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                {websiteUrl.replace(/^https?:\/\//, "")}
+              </a>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Stats */}
+      <div className="mt-8 grid grid-cols-4 gap-3">
+        {[
+          { value: workspaces?.length ?? 0, label: "Workspaces", icon: Folder, to: "/me/repos" },
+          { value: 0, label: "Repositories", icon: GitFork, to: "/me/repos" },
+          { value: 0, label: "Stars", icon: Star, to: "/me/stars" },
+          { value: relationCounts?.followers ?? 0, label: "Followers", icon: Users, to: "/me/following" },
+        ].map((stat) => (
+          <Link
+            className="group rounded-lg border border-border bg-card px-4 py-3 transition-colors hover:border-primary/20"
+            key={stat.label}
+            to={stat.to}
+          >
+            <div className="flex items-center justify-between">
+              <p className="text-lg font-heading font-bold text-foreground">{stat.value}</p>
+              <stat.icon className="size-3.5 text-muted-foreground group-hover:text-primary transition-colors" />
+            </div>
+            <p className="mt-1 font-mono text-[10px] uppercase tracking-widest text-muted-foreground">
+              {stat.label}
+            </p>
+          </Link>
+        ))}
+      </div>
+
+      {/* Contribution heatmap */}
+      <ContributionHeatmap />
+
+      {/* Bottom: Workspaces + Activity */}
+      <div className="mt-16 grid grid-cols-2 gap-12">
+        <WorkspaceList workspaces={workspaces} />
+        <ActivityFeed relationCounts={relationCounts} />
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/me/repos.tsx b/src/page/me/repos.tsx
new file mode 100644
index 0000000..0a3c05b
--- /dev/null
+++ b/src/page/me/repos.tsx
@@ -0,0 +1,80 @@
+import { useQuery } from "@tanstack/react-query";
+import { Link } from "react-router";
+import { client } from "@/client";
+import { GitFork, Search, ChevronRight } from "lucide-react";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import { Input } from "@/components/ui/input";
+
+export default function MeReposPage() {
+  const { data: workspaces = [], isLoading } = useQuery({
+    queryKey: ["workspace", "my"],
+    queryFn: async () => {
+      const res = await client.workspaceMyWorkspaces();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  return (
+    <div className="mx-auto max-w-3xl px-8 py-10">
+      <div className="flex items-start justify-between">
+        <div>
+          <h1 className="text-xl font-heading font-bold text-foreground">Repositories</h1>
+          <p className="mt-1 text-sm text-muted-foreground">Browse your workspaces and their repositories</p>
+        </div>
+        <div className="relative w-56">
+          <Search className="absolute left-3 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+          <Input className="h-9 rounded-lg border-border bg-card pl-8 text-sm" placeholder="Search..." />
+        </div>
+      </div>
+
+      <div className="mt-8 space-y-3">
+        <h2 className="font-mono text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+          Your workspaces
+        </h2>
+
+        {isLoading ? (
+          <div className="space-y-4 mt-4">
+            {Array.from({ length: 3 }).map((_, i) => (
+              <div className="h-16 animate-pulse rounded-lg bg-muted" key={i} />
+            ))}
+          </div>
+        ) : workspaces.length > 0 ? (
+          <div className="mt-4 space-y-3">
+            {workspaces.map((ws) => (
+              <Link
+                className="group flex items-center gap-4 rounded-lg border border-border bg-card px-5 py-4 transition-colors hover:border-primary/20"
+                key={ws.name}
+                to={`/${ws.name}/repos`}
+              >
+                <span
+                  className={`grid size-8 place-items-center rounded-lg bg-gradient-to-br text-xs font-bold text-white ${workspaceColor(ws.name)}`}
+                >
+                  {ws.avatar_url ? <img alt="" className="size-full object-cover" src={ws.avatar_url} /> : workspaceInitial(ws.name)}
+                </span>
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2">
+                    <span className="font-heading font-semibold text-foreground">{ws.name}</span>
+                    {ws.owner && (
+                      <span className="rounded-md border border-border px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground">Owner</span>
+                    )}
+                    {ws.admin && !ws.owner && (
+                      <span className="rounded-md border border-border px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground">Admin</span>
+                    )}
+                  </div>
+                  <p className="text-xs text-muted-foreground truncate">{ws.description}</p>
+                </div>
+                <ChevronRight className="size-4 text-muted-foreground group-hover:text-foreground transition-colors" />
+              </Link>
+            ))}
+          </div>
+        ) : (
+          <div className="mt-8 text-center py-8">
+            <GitFork className="mx-auto size-6 text-muted-foreground/30" />
+            <p className="mt-4 text-sm text-muted-foreground">No workspaces yet</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/me/stars.tsx b/src/page/me/stars.tsx
new file mode 100644
index 0000000..0fa083c
--- /dev/null
+++ b/src/page/me/stars.tsx
@@ -0,0 +1,18 @@
+import { Star } from "lucide-react";
+
+export default function MeStarsPage() {
+  return (
+    <div className="mx-auto max-w-2xl px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Stars</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Repositories and projects you starred</p>
+
+      <div className="mt-20 text-center">
+        <Star className="mx-auto size-8 text-muted-foreground/30" />
+        <p className="mt-4 font-heading font-medium text-muted-foreground">No stars yet</p>
+        <p className="mt-2 text-sm text-muted-foreground">
+          Star repositories to keep track of projects you find interesting
+        </p>
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/accessibility.tsx b/src/page/settings/accessibility.tsx
new file mode 100644
index 0000000..0f76da2
--- /dev/null
+++ b/src/page/settings/accessibility.tsx
@@ -0,0 +1,110 @@
+import { useUserConfig, useUpdateAccessibility } from "./hooks";
+import { Switch } from "@/components/ui/switch";
+import { Label } from "@/components/ui/label";
+import { Slider } from "@/components/ui/slider";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+
+const colorBlindModes = [
+  { value: "none", label: "None" },
+  { value: "protanopia", label: "Protanopia (red-blind)" },
+  { value: "deuteranopia", label: "Deuteranopia (green-blind)" },
+  { value: "tritanopia", label: "Tritanopia (blue-blind)" },
+];
+
+export default function SettingsAccessibilityPage() {
+  const { data: config, isLoading } = useUserConfig();
+  const update = useUpdateAccessibility();
+  const accessibility = config?.accessibility;
+  const fontScale = accessibility?.font_scale_percent ?? 100;
+
+  return (
+    <div className="px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Accessibility</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Adjust the interface for your needs</p>
+
+      {isLoading ? (
+        <div className="mt-8 space-y-4">
+          {Array.from({ length: 3 }).map((_, i) => (
+            <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+          ))}
+        </div>
+      ) : (
+        <div className="mt-8 space-y-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>Font scale</CardTitle>
+              <CardDescription>Adjust text size across the interface ({fontScale}%)</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Slider
+                min={75}
+                max={150}
+                step={5}
+                value={[fontScale]}
+                onValueChange={(v) => {
+                  const scale = typeof v === "number" ? v : (v as number[])[0];
+                  update.mutate({ font_scale_percent: scale });
+                }}
+              />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Color blind mode</CardTitle>
+              <CardDescription>Adjust colors for various types of color vision deficiency</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={accessibility?.color_blind_mode ?? "none"}
+                onValueChange={(v) => update.mutate({ color_blind_mode: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {colorBlindModes.map((m) => (
+                    <SelectItem key={m.value} value={m.value}>{m.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Display adjustments</CardTitle>
+              <CardDescription>Additional visual and interaction settings</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                  <Label>High contrast</Label>
+                  <Switch
+                    checked={accessibility?.high_contrast ?? false}
+                    onCheckedChange={(v) => update.mutate({ high_contrast: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Reduce motion</Label>
+                  <Switch
+                    checked={accessibility?.reduce_motion ?? false}
+                    onCheckedChange={(v) => update.mutate({ reduce_motion: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Screen reader optimized</Label>
+                  <Switch
+                    checked={accessibility?.screen_reader_optimized ?? false}
+                    onCheckedChange={(v) => update.mutate({ screen_reader_optimized: v })}
+                  />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/appearance.tsx b/src/page/settings/appearance.tsx
new file mode 100644
index 0000000..622cb9e
--- /dev/null
+++ b/src/page/settings/appearance.tsx
@@ -0,0 +1,141 @@
+import { useUserConfig, useUpdateAppearance } from "./hooks";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Label } from "@/components/ui/label";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+
+const themes = [
+  { value: "light", label: "Light" },
+  { value: "dark", label: "Dark" },
+  { value: "system", label: "System" },
+];
+
+const codeThemes = [
+  { value: "github-light", label: "GitHub Light" },
+  { value: "github-dark", label: "GitHub Dark" },
+  { value: "vs", label: "VS Code" },
+  { value: "monokai", label: "Monokai" },
+  { value: "solarized-light", label: "Solarized Light" },
+  { value: "solarized-dark", label: "Solarized Dark" },
+  { value: "one-dark", label: "One Dark" },
+];
+
+const densities = [
+  { value: "compact", label: "Compact" },
+  { value: "default", label: "Default" },
+  { value: "comfortable", label: "Comfortable" },
+];
+
+export default function SettingsAppearancePage() {
+  const { data: config, isLoading } = useUserConfig();
+  const update = useUpdateAppearance();
+  const appearance = config?.appearance;
+
+  return (
+    <div className="px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Appearance</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Customize how the interface looks and feels</p>
+
+      {isLoading ? (
+        <div className="mt-8 space-y-4">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+          ))}
+        </div>
+      ) : (
+        <div className="mt-8 space-y-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>Theme</CardTitle>
+              <CardDescription>Select your preferred color theme</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={appearance?.theme ?? "system"}
+                onValueChange={(v) => update.mutate({ theme: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {themes.map((t) => (
+                    <SelectItem key={t.value} value={t.value}>{t.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Code Theme</CardTitle>
+              <CardDescription>Syntax highlighting style for code blocks</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={appearance?.code_theme ?? "github-dark"}
+                onValueChange={(v) => update.mutate({ code_theme: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {codeThemes.map((t) => (
+                    <SelectItem key={t.value} value={t.value}>{t.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Layout Density</CardTitle>
+              <CardDescription>Control spacing and sizing across the interface</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={appearance?.layout_density ?? "default"}
+                onValueChange={(v) => update.mutate({ layout_density: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {densities.map((d) => (
+                    <SelectItem key={d.value} value={d.value}>{d.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Editor</CardTitle>
+              <CardDescription>Code display preferences</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                  <Label>Show line numbers</Label>
+                  <Switch
+                    checked={appearance?.show_line_numbers ?? true}
+                    onCheckedChange={(v) => update.mutate({ show_line_numbers: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Collapsed sidebar</Label>
+                  <Switch
+                    checked={appearance?.sidebar_collapsed ?? false}
+                    onCheckedChange={(v) => update.mutate({ sidebar_collapsed: v })}
+                  />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/hooks.ts b/src/page/settings/hooks.ts
new file mode 100644
index 0000000..561d17a
--- /dev/null
+++ b/src/page/settings/hooks.ts
@@ -0,0 +1,75 @@
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import type {
+  UpdateUserProfileConfig,
+  UpdateUserAppearanceConfig,
+  UpdateUserNotificationConfig,
+  UpdateUserPrivacyConfig,
+  UpdateUserAccessibilityConfig,
+} from "@/client";
+
+export function useUserConfig() {
+  return useQuery({
+    queryKey: ["user", "config"],
+    queryFn: async () => {
+      const res = await client.userConfig();
+      return res.data;
+    },
+    retry: false,
+  });
+}
+
+export function useUpdateProfile() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: UpdateUserProfileConfig) => {
+      const res = await client.userUpdateProfile(data);
+      return res.data;
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "config"] }),
+  });
+}
+
+export function useUpdateAppearance() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: UpdateUserAppearanceConfig) => {
+      const res = await client.userUpdateAppearance(data);
+      return res.data;
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "config"] }),
+  });
+}
+
+export function useUpdateNotification() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: UpdateUserNotificationConfig) => {
+      const res = await client.userUpdateNotification(data);
+      return res.data;
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "config"] }),
+  });
+}
+
+export function useUpdatePrivacy() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: UpdateUserPrivacyConfig) => {
+      const res = await client.userUpdatePrivacy(data);
+      return res.data;
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "config"] }),
+  });
+}
+
+export function useUpdateAccessibility() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: UpdateUserAccessibilityConfig) => {
+      const res = await client.userUpdateAccessibility(data);
+      return res.data;
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "config"] }),
+  });
+}
\ No newline at end of file
diff --git a/src/page/settings/notifications.tsx b/src/page/settings/notifications.tsx
new file mode 100644
index 0000000..1fde424
--- /dev/null
+++ b/src/page/settings/notifications.tsx
@@ -0,0 +1,172 @@
+import { useUserConfig, useUpdateNotification } from "./hooks";
+import { Switch } from "@/components/ui/switch";
+import { Label } from "@/components/ui/label";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Input } from "@/components/ui/input";
+
+const digestModes = [
+  { value: "none", label: "None" },
+  { value: "daily", label: "Daily" },
+  { value: "weekly", label: "Weekly" },
+];
+
+function minuteToTime(minute: number) {
+  const h = Math.floor(minute / 60);
+  const m = minute % 60;
+  return `${h.toString().padStart(2, "0")}:${m.toString().padStart(2, "0")}`;
+}
+
+function timeToMinute(time: string) {
+  const [h, m] = time.split(":").map(Number);
+  return h * 60 + m;
+}
+
+export default function SettingsNotificationsPage() {
+  const { data: config, isLoading } = useUserConfig();
+  const update = useUpdateNotification();
+  const notif = config?.notifications;
+
+  return (
+    <div className="px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Notifications</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Control how and when you receive notifications</p>
+
+      {isLoading ? (
+        <div className="mt-8 space-y-4">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+          ))}
+        </div>
+      ) : (
+        <div className="mt-8 space-y-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>Channels</CardTitle>
+              <CardDescription>Choose which notification channels to enable</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                  <Label>In-app notifications</Label>
+                  <Switch
+                    checked={notif?.in_app_enabled ?? true}
+                    onCheckedChange={(v) => update.mutate({ in_app_enabled: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Email notifications</Label>
+                  <Switch
+                    checked={notif?.email_enabled ?? true}
+                    onCheckedChange={(v) => update.mutate({ email_enabled: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Push notifications</Label>
+                  <Switch
+                    checked={notif?.push_enabled ?? false}
+                    onCheckedChange={(v) => update.mutate({ push_enabled: v })}
+                  />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Content</CardTitle>
+              <CardDescription>Select which types of notifications you want to receive</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                  <Label>Security alerts</Label>
+                  <Switch
+                    checked={notif?.security_enabled ?? true}
+                    onCheckedChange={(v) => update.mutate({ security_enabled: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Product updates</Label>
+                  <Switch
+                    checked={notif?.product_enabled ?? true}
+                    onCheckedChange={(v) => update.mutate({ product_enabled: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Marketing</Label>
+                  <Switch
+                    checked={notif?.marketing_enabled ?? false}
+                    onCheckedChange={(v) => update.mutate({ marketing_enabled: v })}
+                  />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Digest</CardTitle>
+              <CardDescription>Choose how often to receive notification digests</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={notif?.digest_mode ?? "daily"}
+                onValueChange={(v) => update.mutate({ digest_mode: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {digestModes.map((d) => (
+                    <SelectItem key={d.value} value={d.value}>{d.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Do Not Disturb</CardTitle>
+              <CardDescription>Pause notifications during specific hours</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                  <Label>Enable DND</Label>
+                  <Switch
+                    checked={notif?.dnd_enabled ?? false}
+                    onCheckedChange={(v) => update.mutate({ dnd_enabled: v })}
+                  />
+                </div>
+                {(notif?.dnd_enabled ?? false) && (
+                  <div className="flex items-center gap-4">
+                    <div className="flex items-center gap-2">
+                      <Label>Start</Label>
+                      <Input
+                        className="w-20 h-8 text-sm font-mono"
+                        type="time"
+                        value={minuteToTime(notif?.dnd_start_minute ?? 0)}
+                        onChange={(e) => update.mutate({ dnd_start_minute: timeToMinute(e.target.value) })}
+                      />
+                    </div>
+                    <div className="flex items-center gap-2">
+                      <Label>End</Label>
+                      <Input
+                        className="w-20 h-8 text-sm font-mono"
+                        type="time"
+                        value={minuteToTime(notif?.dnd_end_minute ?? 480)}
+                        onChange={(e) => update.mutate({ dnd_end_minute: timeToMinute(e.target.value) })}
+                      />
+                    </div>
+                  </div>
+                )}
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/privacy.tsx b/src/page/settings/privacy.tsx
new file mode 100644
index 0000000..f0541c1
--- /dev/null
+++ b/src/page/settings/privacy.tsx
@@ -0,0 +1,132 @@
+import { useUserConfig, useUpdatePrivacy } from "./hooks";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Label } from "@/components/ui/label";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+
+const visibilityOptions = [
+  { value: "public", label: "Public" },
+  { value: "members", label: "Members only" },
+  { value: "private", label: "Private" },
+];
+
+export default function SettingsPrivacyPage() {
+  const { data: config, isLoading } = useUserConfig();
+  const update = useUpdatePrivacy();
+  const privacy = config?.privacy;
+
+  return (
+    <div className="px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Privacy</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Control who can see your information and activity</p>
+
+      {isLoading ? (
+        <div className="mt-8 space-y-4">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+          ))}
+        </div>
+      ) : (
+        <div className="mt-8 space-y-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>Profile visibility</CardTitle>
+              <CardDescription>Who can see your profile page</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={privacy?.profile_visibility ?? "public"}
+                onValueChange={(v) => update.mutate({ profile_visibility: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {visibilityOptions.map((opt) => (
+                    <SelectItem key={opt.value} value={opt.value}>{opt.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Activity visibility</CardTitle>
+              <CardDescription>Who can see your contribution activity</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={privacy?.activity_visibility ?? "public"}
+                onValueChange={(v) => update.mutate({ activity_visibility: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {visibilityOptions.map((opt) => (
+                    <SelectItem key={opt.value} value={opt.value}>{opt.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Email visibility</CardTitle>
+              <CardDescription>Who can see your email address</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={privacy?.email_visibility ?? "private"}
+                onValueChange={(v) => update.mutate({ email_visibility: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {visibilityOptions.map((opt) => (
+                    <SelectItem key={opt.value} value={opt.value}>{opt.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Other settings</CardTitle>
+              <CardDescription>Additional privacy controls</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                  <Label>Show online status</Label>
+                  <Switch
+                    checked={privacy?.show_online_status ?? true}
+                    onCheckedChange={(v) => update.mutate({ show_online_status: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Allow direct messages</Label>
+                  <Switch
+                    checked={privacy?.allow_direct_messages ?? true}
+                    onCheckedChange={(v) => update.mutate({ allow_direct_messages: v })}
+                  />
+                </div>
+                <div className="flex items-center justify-between">
+                  <Label>Allow search indexing</Label>
+                  <Switch
+                    checked={privacy?.allow_search_indexing ?? true}
+                    onCheckedChange={(v) => update.mutate({ allow_search_indexing: v })}
+                  />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/profile.tsx b/src/page/settings/profile.tsx
new file mode 100644
index 0000000..30aa3ab
--- /dev/null
+++ b/src/page/settings/profile.tsx
@@ -0,0 +1,108 @@
+import { useUserConfig, useUpdateProfile } from "./hooks";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import AvatarUploader from "@/components/ui/avatar-uploader";
+import { useAuth } from "@/context/auth-context";
+import { useQueryClient } from "@tanstack/react-query";
+
+const timezones = [
+  "UTC", "America/New_York", "America/Chicago", "America/Los_Angeles",
+  "America/Denver", "Europe/London", "Europe/Berlin", "Europe/Paris",
+  "Asia/Shanghai", "Asia/Tokyo", "Asia/Kolkata", "Asia/Singapore",
+  "Australia/Sydney", "Pacific/Auckland",
+];
+
+const languages = [
+  { value: "en", label: "English" },
+  { value: "zh", label: "Chinese" },
+  { value: "ja", label: "Japanese" },
+  { value: "ko", label: "Korean" },
+  { value: "de", label: "German" },
+  { value: "fr", label: "French" },
+  { value: "es", label: "Spanish" },
+];
+
+export default function SettingsProfilePage() {
+  const { data: config, isLoading } = useUserConfig();
+  const updateProfile = useUpdateProfile();
+  const profile = config?.profile;
+  const { user } = useAuth();
+  const queryClient = useQueryClient();
+
+  return (
+    <div className="px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Profile</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Manage your language, timezone, and display preferences</p>
+
+      {isLoading ? (
+        <div className="mt-8 space-y-4">
+          {Array.from({ length: 3 }).map((_, i) => (
+            <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+          ))}
+        </div>
+      ) : (
+        <div className="mt-8 space-y-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>Avatar</CardTitle>
+              <CardDescription>Upload a profile photo</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <AvatarUploader
+                currentUrl={user?.avatar_url}
+                label="Profile photo"
+                onUploaded={() => {
+                  queryClient.invalidateQueries({ queryKey: ["auth", "me"] });
+                }}
+                uploadEndpoint="/api/v1/user/avatar"
+              />
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader>
+              <CardTitle>Language</CardTitle>
+              <CardDescription>Choose your preferred interface language</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={profile?.language ?? "en"}
+                onValueChange={(v) => updateProfile.mutate({ language: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {languages.map((lang) => (
+                    <SelectItem key={lang.value} value={lang.value}>{lang.label}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Timezone</CardTitle>
+              <CardDescription>Select your local timezone for accurate date/time display</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Select
+                value={profile?.timezone ?? "UTC"}
+                onValueChange={(v) => updateProfile.mutate({ timezone: v })}
+              >
+                <SelectTrigger className="w-48">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {timezones.map((tz) => (
+                    <SelectItem key={tz} value={tz}>{tz}</SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </CardContent>
+          </Card>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/security.tsx b/src/page/settings/security.tsx
new file mode 100644
index 0000000..5d0dce3
--- /dev/null
+++ b/src/page/settings/security.tsx
@@ -0,0 +1,163 @@
+import { useQuery, useMutation } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Shield, ShieldOff, Mail } from "lucide-react";
+
+function TwoFactorSection() {
+  const { data: status, isLoading } = useQuery({
+    queryKey: ["auth", "2fa", "status"],
+    queryFn: async () => {
+      const res = await client.authStatus2fa();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const enable2fa = useMutation({
+    mutationFn: async () => {
+      const res = await client.authEnable2fa();
+      return res.data;
+    },
+  });
+
+  if (isLoading) {
+    return <div className="h-16 animate-pulse rounded-lg bg-muted" />;
+  }
+
+  if (status?.is_enabled) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Shield className="size-4 text-green-600" />
+            Two-factor authentication enabled
+          </CardTitle>
+          <CardDescription>Your account is protected with 2FA</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm text-muted-foreground">
+            Method: {status.method ?? "TOTP"}
+            {status.has_backup_codes ? " — Backup codes available" : " — No backup codes"}
+          </p>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <ShieldOff className="size-4 text-amber-600" />
+          Two-factor authentication
+        </CardTitle>
+        <CardDescription>Add an extra layer of security to your account</CardDescription>
+      </CardHeader>
+      <CardContent>
+        {enable2fa.data ? (
+          <div className="space-y-4">
+            <p className="text-sm text-foreground font-medium">
+              Scan this QR code with your authenticator app, then enter the code below to verify.
+            </p>
+            <img alt="2FA QR code" className="size-48 rounded-lg border border-border" src={enable2fa.data.qr_code} />
+            <p className="font-mono text-xs text-muted-foreground">Secret: {enable2fa.data.secret}</p>
+            <div className="space-y-2">
+              <p className="font-heading font-medium text-sm text-foreground">Backup codes (save these!)</p>
+              <div className="grid grid-cols-2 gap-1">
+                {enable2fa.data.backup_codes.map((code) => (
+                  <p className="font-mono text-xs text-muted-foreground" key={code}>{code}</p>
+                ))}
+              </div>
+            </div>
+          </div>
+        ) : (
+          <Button onClick={() => enable2fa.mutate()}>
+            Enable 2FA
+          </Button>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+function EmailSection() {
+  const { data: emailData, isLoading } = useQuery({
+    queryKey: ["auth", "email"],
+    queryFn: async () => {
+      const res = await client.authGetEmail();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const changeEmail = useMutation({
+    mutationFn: async (data: { new_email: string; password: string }) => {
+      await client.authEmailChangeRequest(data);
+    },
+  });
+
+  if (isLoading) {
+    return <div className="h-16 animate-pulse rounded-lg bg-muted" />;
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Mail className="size-4" />
+          Email address
+        </CardTitle>
+        <CardDescription>Your email is used for notifications and account recovery</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p className="font-mono text-sm text-foreground">{emailData?.email ?? "Not set"}</p>
+        {changeEmail.isIdle && (
+          <form
+            className="mt-4 space-y-3"
+            onSubmit={(e) => {
+              e.preventDefault();
+              const fd = new FormData(e.currentTarget);
+              changeEmail.mutate({
+                new_email: fd.get("new_email") as string,
+                password: fd.get("password") as string,
+              });
+            }}
+          >
+            <div>
+              <Label>New email</Label>
+              <Input className="mt-1 h-9" name="new_email" placeholder="new@email.com" required type="email" />
+            </div>
+            <div>
+              <Label>Current password</Label>
+              <Input className="mt-1 h-9" name="password" placeholder="Confirm password" required type="password" />
+            </div>
+            <Button size="sm" type="submit">Change email</Button>
+          </form>
+        )}
+        {changeEmail.isSuccess && (
+          <p className="mt-4 text-sm text-green-600">Verification email sent. Check your inbox.</p>
+        )}
+        {changeEmail.isError && (
+          <p className="mt-4 text-sm text-destructive">Failed to change email. Please try again.</p>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function SettingsSecurityPage() {
+  return (
+    <div className="px-8 py-10">
+      <h1 className="text-xl font-heading font-bold text-foreground">Security</h1>
+      <p className="mt-1 text-sm text-muted-foreground">Manage your account security, 2FA, and credentials</p>
+
+      <div className="mt-8 space-y-6">
+        <TwoFactorSection />
+        <EmailSection />
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/ssh-keys.tsx b/src/page/settings/ssh-keys.tsx
new file mode 100644
index 0000000..2fc9c10
--- /dev/null
+++ b/src/page/settings/ssh-keys.tsx
@@ -0,0 +1,135 @@
+import { useState } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type CreateUserSshKey } from "@/client";
+import { Card, CardContent } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { Terminal, Trash2 } from "lucide-react";
+
+export default function SettingsSshKeysPage() {
+  const qc = useQueryClient();
+  const [newTitle, setNewTitle] = useState("");
+  const [newKey, setNewKey] = useState("");
+
+  const { data: keys = [], isLoading } = useQuery({
+    queryKey: ["user", "ssh-keys"],
+    queryFn: async () => {
+      const res = await client.userListSshKeys();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const addKey = useMutation({
+    mutationFn: async (data: CreateUserSshKey) => {
+      const res = await client.userAddSshKey(data);
+      return res.data;
+    },
+    onSuccess: () => {
+      setNewTitle("");
+      setNewKey("");
+      qc.invalidateQueries({ queryKey: ["user", "ssh-keys"] });
+    },
+  });
+
+  const revokeKey = useMutation({
+    mutationFn: async (id: number) => {
+      await client.userRevokeSshKey(id);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "ssh-keys"] }),
+  });
+
+  const activeKeys = keys.filter((k) => !k.is_revoked);
+
+  return (
+    <div className="px-8 py-10">
+      <div className="flex items-start justify-between">
+        <div>
+          <h1 className="text-xl font-heading font-bold text-foreground">SSH Keys</h1>
+          <p className="mt-1 text-sm text-muted-foreground">Manage SSH keys for Git operations and secure access</p>
+        </div>
+        <Dialog onOpenChange={(open) => { if (!open) { setNewTitle(""); setNewKey(""); } }}>
+          <DialogTrigger render={<Button size="sm">Add SSH key</Button>} />
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Add SSH key</DialogTitle>
+            </DialogHeader>
+            <form
+              className="space-y-3"
+              onSubmit={(e) => {
+                e.preventDefault();
+                addKey.mutate({ title: newTitle, public_key: newKey });
+              }}
+            >
+              <div>
+                <Label>Title</Label>
+                <Input
+                  className="mt-1 h-9"
+                  placeholder="e.g. Laptop key"
+                  value={newTitle}
+                  onChange={(e) => setNewTitle(e.target.value)}
+                />
+              </div>
+              <div>
+                <Label>Public key</Label>
+                <textarea
+                  className="mt-1 w-full rounded-lg border border-input bg-transparent px-3 py-2 text-sm font-mono focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50"
+                  placeholder="ssh-ed25519 AAAA..."
+                  rows={4}
+                  value={newKey}
+                  onChange={(e) => setNewKey(e.target.value)}
+                />
+              </div>
+              <Button size="sm" type="submit" disabled={!newTitle || !newKey}>Add key</Button>
+            </form>
+          </DialogContent>
+        </Dialog>
+      </div>
+
+      <div className="mt-8">
+        {isLoading ? (
+          <div className="space-y-3">
+            {Array.from({ length: 2 }).map((_, i) => (
+              <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+            ))}
+          </div>
+        ) : activeKeys.length > 0 ? (
+          <div className="space-y-3">
+            {activeKeys.map((key) => (
+              <Card key={key.id}>
+                <CardContent className="flex items-center justify-between">
+                  <div className="flex items-center gap-3 min-w-0">
+                    <Terminal className="size-4 text-muted-foreground shrink-0" />
+                    <div className="min-w-0">
+                      <p className="font-heading font-medium text-foreground">{key.title}</p>
+                      <p className="font-mono text-xs text-muted-foreground">
+                        {key.key_type} {key.key_bits ?? "?"}bit · {key.fingerprint.slice(0, 24)}
+                        {key.is_verified ? " · Verified" : " · Unverified"}
+                        · Added {new Date(key.created_at).toLocaleDateString()}
+                      </p>
+                    </div>
+                  </div>
+                  <Button
+                    className="size-8 text-destructive hover:text-destructive"
+                    onClick={() => revokeKey.mutate(key.id)}
+                    size="icon"
+                    variant="ghost"
+                  >
+                    <Trash2 className="size-4" />
+                  </Button>
+                </CardContent>
+              </Card>
+            ))}
+          </div>
+        ) : (
+          <div className="py-10 text-center">
+            <Terminal className="mx-auto size-6 text-muted-foreground/30" />
+            <p className="mt-4 text-sm text-muted-foreground">No SSH keys added</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/settings/tokens.tsx b/src/page/settings/tokens.tsx
new file mode 100644
index 0000000..47ab8d9
--- /dev/null
+++ b/src/page/settings/tokens.tsx
@@ -0,0 +1,151 @@
+import { useState } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type CreateUserAccessToken } from "@/client";
+import { Card, CardContent } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogClose } from "@/components/ui/dialog";
+import { Key, Trash2, Copy } from "lucide-react";
+
+export default function SettingsTokensPage() {
+  const qc = useQueryClient();
+  const [newTokenName, setNewTokenName] = useState("");
+  const [createdToken, setCreatedToken] = useState("");
+
+  const { data: tokens = [], isLoading } = useQuery({
+    queryKey: ["user", "access-tokens"],
+    queryFn: async () => {
+      const res = await client.userListAccessTokens();
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const createToken = useMutation({
+    mutationFn: async (data: CreateUserAccessToken) => {
+      const res = await client.userCreateAccessToken(data);
+      return res.data;
+    },
+    onSuccess: (data) => {
+      setCreatedToken(data.token);
+      qc.invalidateQueries({ queryKey: ["user", "access-tokens"] });
+    },
+  });
+
+  const revokeToken = useMutation({
+    mutationFn: async (id: number) => {
+      await client.userRevokeAccessToken(id);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["user", "access-tokens"] }),
+  });
+
+  const activeTokens = tokens.filter((t) => !t.is_revoked);
+
+  return (
+    <div className="px-8 py-10">
+      <div className="flex items-start justify-between">
+        <div>
+          <h1 className="text-xl font-heading font-bold text-foreground">Access Tokens</h1>
+          <p className="mt-1 text-sm text-muted-foreground">Manage personal access tokens for API authentication</p>
+        </div>
+        <Dialog
+          onOpenChange={(open) => {
+            if (!open) {
+              setNewTokenName("");
+              setCreatedToken("");
+            }
+          }}
+        >
+          <DialogTrigger render={<Button size="sm">New token</Button>} />
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Create access token</DialogTitle>
+            </DialogHeader>
+            {createdToken ? (
+              <div className="space-y-3">
+                <p className="text-sm text-foreground font-medium">Token created! Copy it now — it won't be shown again.</p>
+                <div className="flex items-center gap-2">
+                  <code className="flex-1 rounded-md bg-muted px-3 py-2 font-mono text-xs text-foreground break-all">
+                    {createdToken}
+                  </code>
+                  <Button
+                    className="size-8"
+                    onClick={() => navigator.clipboard.writeText(createdToken)}
+                    size="icon"
+                    variant="outline"
+                  >
+                    <Copy className="size-4" />
+                  </Button>
+                </div>
+                <DialogClose render={<Button variant="outline">Done</Button>} />
+              </div>
+            ) : (
+              <form
+                className="space-y-3"
+                onSubmit={(e) => {
+                  e.preventDefault();
+                  createToken.mutate({ name: newTokenName, scopes: ["read"] });
+                }}
+              >
+                <div>
+                  <Label>Token name</Label>
+                  <Input
+                    className="mt-1 h-9"
+                    placeholder="e.g. CI pipeline"
+                    value={newTokenName}
+                    onChange={(e) => setNewTokenName(e.target.value)}
+                  />
+                </div>
+                <Button size="sm" type="submit" disabled={!newTokenName}>Create token</Button>
+              </form>
+            )}
+          </DialogContent>
+        </Dialog>
+      </div>
+
+      <div className="mt-8">
+        {isLoading ? (
+          <div className="space-y-3">
+            {Array.from({ length: 2 }).map((_, i) => (
+              <div className="h-12 animate-pulse rounded-lg bg-muted" key={i} />
+            ))}
+          </div>
+        ) : activeTokens.length > 0 ? (
+          <div className="space-y-3">
+            {activeTokens.map((token) => (
+              <Card key={token.id}>
+                <CardContent className="flex items-center justify-between">
+                  <div className="flex items-center gap-3">
+                    <Key className="size-4 text-muted-foreground" />
+                    <div>
+                      <p className="font-heading font-medium text-foreground">{token.name}</p>
+                      <p className="font-mono text-xs text-muted-foreground">
+                        Created {new Date(token.created_at).toLocaleDateString()}
+                        {token.expires_at && ` · Expires ${new Date(token.expires_at).toLocaleDateString()}`}
+                        · Scopes: {token.scopes.join(", ")}
+                      </p>
+                    </div>
+                  </div>
+                  <Button
+                    className="size-8 text-destructive hover:text-destructive"
+                    onClick={() => revokeToken.mutate(token.id)}
+                    size="icon"
+                    variant="ghost"
+                  >
+                    <Trash2 className="size-4" />
+                  </Button>
+                </CardContent>
+              </Card>
+            ))}
+          </div>
+        ) : (
+          <div className="py-10 text-center">
+            <Key className="mx-auto size-6 text-muted-foreground/30" />
+            <p className="mt-4 text-sm text-muted-foreground">No active tokens</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/channel/channel-header.tsx b/src/page/workspace/channel/channel-header.tsx
new file mode 100644
index 0000000..727c488
--- /dev/null
+++ b/src/page/workspace/channel/channel-header.tsx
@@ -0,0 +1,109 @@
+import { Hash, MessageSquare, Settings, Users } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import type { Room } from "./channel-sidebar";
+import type { Thread } from "./thread-sidebar";
+
+type Props = {
+  room: Room;
+  threads: Thread[];
+  onToggleThreads: () => void;
+  onToggleSettings: () => void;
+  memberCount?: number;
+};
+
+export function ChannelHeader({
+  room,
+  threads,
+  onToggleThreads,
+  onToggleSettings,
+  memberCount,
+}: Props) {
+  const activeThreads = threads.filter((t) => !t.archived && !t.locked).length;
+
+  return (
+    <header className="flex h-[52px] shrink-0 items-center gap-3 border-b border-border/50 bg-background/70 px-5 backdrop-blur-md">
+      <div className="flex min-w-0 items-center gap-2.5">
+        <span className="grid size-8 shrink-0 place-items-center rounded-lg bg-gradient-to-br from-primary/10 to-primary/[0.03] ring-1 ring-primary/[0.08]">
+          <Hash className="size-3.5 text-primary/60" />
+        </span>
+        <div className="flex min-w-0 items-baseline gap-2">
+          <h3 className="truncate text-[15px] font-semibold text-foreground tracking-tight">
+            {room.name}
+          </h3>
+          {room.topic && (
+            <Tooltip>
+              <TooltipTrigger className="hidden sm:block">
+                <span className="max-w-[200px] cursor-default truncate text-[13px] text-muted-foreground/40">
+                  {room.topic}
+                </span>
+              </TooltipTrigger>
+              <TooltipContent
+                className="max-w-sm text-xs leading-relaxed"
+                side="bottom"
+              >
+                {room.topic}
+              </TooltipContent>
+            </Tooltip>
+          )}
+        </div>
+      </div>
+
+      <div className="ml-auto flex items-center gap-0.5">
+        {typeof memberCount === "number" && memberCount > 0 && (
+          <span className="flex items-center gap-1.5 rounded-lg px-2.5 py-1 text-[12px] text-muted-foreground/60">
+            <Users className="size-3.5" />
+            <span className="tabular-nums">{memberCount}</span>
+          </span>
+        )}
+
+        <Tooltip>
+          <TooltipTrigger>
+            <Button
+              aria-label="Toggle threads panel"
+              className={cn(
+                "relative size-8 cursor-pointer rounded-lg transition-all duration-150",
+                activeThreads > 0
+                  ? "text-foreground hover:bg-accent/50"
+                  : "text-muted-foreground/50 hover:bg-accent/40 hover:text-foreground",
+              )}
+              onClick={onToggleThreads}
+              size="icon"
+              variant="ghost"
+            >
+              <MessageSquare className="size-[18px]" />
+              {activeThreads > 0 && (
+                <span className="absolute -top-0.5 -right-0.5 flex size-[18px] items-center justify-center rounded-full bg-primary text-[10px] font-semibold text-primary-foreground ring-[2.5px] ring-background shadow-sm">
+                  {activeThreads}
+                </span>
+              )}
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent className="text-xs">
+            Threads{activeThreads > 0 ? ` (${activeThreads} active)` : ""}
+          </TooltipContent>
+        </Tooltip>
+
+        <Tooltip>
+          <TooltipTrigger>
+            <Button
+              aria-label="Channel settings"
+              className="size-8 cursor-pointer rounded-lg text-muted-foreground/50 transition-all duration-150 hover:bg-accent/40 hover:text-foreground"
+              onClick={onToggleSettings}
+              size="icon"
+              variant="ghost"
+            >
+              <Settings className="size-[18px]" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent className="text-xs">Channel settings</TooltipContent>
+        </Tooltip>
+      </div>
+    </header>
+  );
+}
diff --git a/src/page/workspace/channel/channel-sidebar.tsx b/src/page/workspace/channel/channel-sidebar.tsx
new file mode 100644
index 0000000..b8ad4bb
--- /dev/null
+++ b/src/page/workspace/channel/channel-sidebar.tsx
@@ -0,0 +1,262 @@
+import { useMemo, useState } from "react";
+import {
+  ChevronRight,
+  Hash,
+  Lock,
+  Volume2,
+  Plus,
+  MessageSquare,
+  FolderOpen,
+} from "lucide-react";
+import { Link, useLocation, useParams } from "react-router";
+import { cn } from "@/lib/utils";
+
+export type Room = {
+  id: string;
+  name: string;
+  topic?: string | null;
+  room_type: string;
+  is_private: boolean;
+  category?: string | null;
+  workspace_id: string;
+};
+
+export type Category = {
+  id: string;
+  name: string;
+  position: number;
+};
+
+type Props = {
+  rooms: Room[];
+  categories?: Category[];
+  loading: boolean;
+  onCreateChannel?: () => void;
+};
+
+function RoomIcon({ type }: { type: string }) {
+  if (type === "voice")
+    return <Volume2 className="size-[15px] shrink-0 text-muted-foreground/60" />;
+  return <Hash className="size-[15px] shrink-0 text-muted-foreground/60" />;
+}
+
+function RoomLink({
+  room,
+  projectName,
+}: {
+  room: Room;
+  projectName: string;
+}) {
+  const location = useLocation();
+  const active = location.pathname.endsWith(`/channel/${room.id}`);
+
+  return (
+    <Link
+      className={cn(
+        "group flex h-8 items-center gap-2 rounded-md px-2 text-[13px] transition-all duration-150",
+        active
+          ? "bg-primary/[0.08] font-medium text-foreground"
+          : "text-muted-foreground/80 hover:bg-accent/[0.4] hover:text-foreground",
+      )}
+      to={`/${projectName}/channel/${room.id}`}
+    >
+      <span
+        className={cn(
+          "shrink-0 transition-colors duration-150",
+          active && "text-primary/70",
+        )}
+      >
+        <RoomIcon type={room.room_type} />
+      </span>
+      <span className="min-w-0 flex-1 truncate">{room.name}</span>
+      {room.is_private && (
+        <Lock className="size-3 shrink-0 text-muted-foreground/30" />
+      )}
+    </Link>
+  );
+}
+
+function CollapsibleSection({
+  title,
+  icon,
+  defaultOpen = true,
+  count,
+  children,
+}: {
+  title: string;
+  icon: React.ReactNode;
+  defaultOpen?: boolean;
+  count?: number;
+  children: React.ReactNode;
+}) {
+  const [open, setOpen] = useState(defaultOpen);
+
+  return (
+    <div className="mb-0.5">
+      <button
+        className="flex w-full cursor-pointer items-center gap-1.5 rounded-md px-1.5 py-[3px] text-[11px] font-semibold uppercase tracking-[0.06em] text-muted-foreground/40 transition-colors hover:text-muted-foreground/70"
+        onClick={() => setOpen((v) => !v)}
+        type="button"
+      >
+        <ChevronRight
+          className={cn(
+            "size-3.5 shrink-0 transition-transform duration-200",
+            open && "rotate-90",
+          )}
+        />
+        {icon}
+        <span className="flex-1 text-left">{title}</span>
+        {count !== undefined && (
+          <span className="text-[10px] tabular-nums text-muted-foreground/30">
+            {count}
+          </span>
+        )}
+      </button>
+      <div
+        className={cn(
+          "grid transition-[grid-template-rows] duration-200",
+          open ? "grid-rows-[1fr]" : "grid-rows-[0fr]",
+        )}
+      >
+        <div className="overflow-hidden">
+          <div className="space-y-[1px] py-0.5">{children}</div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function SidebarSkeleton() {
+  return (
+    <div className="space-y-1 px-3 py-4">
+      <div className="mb-4 h-3 w-24 animate-pulse rounded bg-muted/40" />
+      {Array.from({ length: 5 }).map((_, i) => (
+        <div
+          className="h-8 animate-pulse rounded-md bg-muted/30"
+          key={i}
+          style={{ animationDelay: `${i * 60}ms` }}
+        />
+      ))}
+    </div>
+  );
+}
+
+export default function ChannelSidebar({
+  rooms,
+  categories = [],
+  loading,
+  onCreateChannel,
+}: Props) {
+  const { projectName = "" } = useParams();
+
+  const { categorized, uncategorized } = useMemo(() => {
+    const categorizedGroups: {
+      id: string;
+      name: string;
+      rooms: Room[];
+    }[] = [];
+    const uncategorizedList: Room[] = [];
+
+    if (categories.length > 0) {
+      const catMap = new Map(
+        categories.map((c) => [c.id, { id: c.id, name: c.name, rooms: [] as Room[] }]),
+      );
+      for (const room of rooms) {
+        const catId = room.category ?? null;
+        const group = catId ? catMap.get(catId) : undefined;
+        if (group) {
+          group.rooms.push(room);
+        } else {
+          uncategorizedList.push(room);
+        }
+      }
+      const sorted = categories.toSorted((a, b) => a.position - b.position);
+      for (const cat of sorted) {
+        const group = catMap.get(cat.id);
+        if (group && group.rooms.length > 0) {
+          categorizedGroups.push(group);
+        }
+      }
+    } else {
+      uncategorizedList.push(...rooms);
+    }
+
+    return {
+      categorized: categorizedGroups,
+      uncategorized: uncategorizedList,
+    };
+  }, [rooms, categories]);
+
+  if (loading) return <SidebarSkeleton />;
+
+  return (
+    <div className="flex h-full flex-col">
+      {/* Header */}
+      <div className="flex h-11 shrink-0 items-center justify-between border-b border-border/40 px-3">
+        <h2 className="truncate text-[11px] font-semibold uppercase tracking-[0.08em] text-muted-foreground/50">
+          {projectName}
+        </h2>
+        {onCreateChannel && (
+          <button
+            aria-label="Create channel"
+            className="inline-flex size-7 items-center justify-center rounded-md text-muted-foreground/40 transition-all duration-150 hover:bg-accent hover:text-foreground"
+            onClick={onCreateChannel}
+            type="button"
+          >
+            <Plus className="size-4" />
+          </button>
+        )}
+      </div>
+
+      {/* Content */}
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-1.5 py-2">
+        {uncategorized.length > 0 && (
+          <CollapsibleSection
+            defaultOpen={true}
+            icon={<Hash className="size-3 text-muted-foreground/40" />}
+            title="Channels"
+          >
+            {uncategorized.map((room) => (
+              <RoomLink key={room.id} projectName={projectName} room={room} />
+            ))}
+          </CollapsibleSection>
+        )}
+
+        {categorized.map((group) => (
+          <CollapsibleSection
+            count={group.rooms.length}
+            defaultOpen={true}
+            icon={<FolderOpen className="size-3 text-muted-foreground/40" />}
+            key={group.id}
+            title={group.name}
+          >
+            {group.rooms.map((room) => (
+              <RoomLink key={room.id} projectName={projectName} room={room} />
+            ))}
+          </CollapsibleSection>
+        ))}
+
+        {rooms.length === 0 && (
+          <div className="flex flex-col items-center px-4 py-20">
+            <div className="grid size-12 place-items-center rounded-2xl bg-muted/30">
+              <MessageSquare className="size-5 text-muted-foreground/25" />
+            </div>
+            <p className="mt-4 text-sm font-medium text-muted-foreground/40">
+              No channels yet
+            </p>
+            {onCreateChannel && (
+              <button
+                className="mt-3 inline-flex cursor-pointer items-center gap-1.5 rounded-lg px-4 py-2 text-sm font-medium text-primary transition-all duration-150 hover:bg-primary/[0.08]"
+                onClick={onCreateChannel}
+                type="button"
+              >
+                <Plus className="size-4" />
+                Create a channel
+              </button>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/page/workspace/channel/channel-thread-panel.tsx b/src/page/workspace/channel/channel-thread-panel.tsx
new file mode 100644
index 0000000..0ac18ef
--- /dev/null
+++ b/src/page/workspace/channel/channel-thread-panel.tsx
@@ -0,0 +1,66 @@
+import { useState, useEffect } from "react";
+import ThreadSidebar from "./thread-sidebar";
+import ThreadPane from "./thread-pane";
+import type { Thread } from "./thread-sidebar";
+
+type Props = {
+  open: boolean;
+  threads: Thread[];
+  roomId: string;
+  onClose: () => void;
+};
+
+export function ChannelThreadPanel({ open, threads, roomId, onClose }: Props) {
+  const [selectedThread, setSelectedThread] = useState<Thread | null>(null);
+
+  // Reset selection when panel closes
+  useEffect(() => {
+    if (!open) {
+      setSelectedThread(null);
+    }
+  }, [open]);
+
+  if (!open) return null;
+
+  return (
+    <>
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0 z-20 bg-background/[0.03] backdrop-blur-[2px]"
+        onClick={onClose}
+      />
+
+      {/* Thread Sidebar (list) */}
+      <div
+        className={`
+          absolute inset-y-0 right-0 z-30 w-80 border-l border-border/30 bg-card shadow-2xl
+          transition-transform duration-300 ease-out
+          ${selectedThread ? "translate-x-full" : "translate-x-0"}
+        `}
+      >
+        <ThreadSidebar
+          onClose={onClose}
+          onSelect={setSelectedThread}
+          threads={threads}
+        />
+      </div>
+
+      {/* Thread Pane (detail) */}
+      <div
+        className={`
+          absolute inset-y-0 right-0 z-40 w-96 border-l border-border/30 bg-card shadow-2xl
+          transition-transform duration-300 ease-out
+          ${selectedThread ? "translate-x-0" : "translate-x-full"}
+        `}
+      >
+        {selectedThread && (
+          <ThreadPane
+            onClose={() => setSelectedThread(null)}
+            roomId={roomId}
+            thread={selectedThread}
+          />
+        )}
+      </div>
+    </>
+  );
+}
diff --git a/src/page/workspace/channel/composer.tsx b/src/page/workspace/channel/composer.tsx
new file mode 100644
index 0000000..ebc5ae9
--- /dev/null
+++ b/src/page/workspace/channel/composer.tsx
@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Reply, Send, X } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+import FileUploadButton from "./file-upload";
+import type { MessageNewService } from "@/socket";
+
+type Props = {
+  roomName: string;
+  replyTarget?: MessageNewService | null;
+  onSend: (content: string) => Promise<void>;
+  onCancelReply?: () => void;
+  onTyping?: (typing: boolean) => void;
+  disabled?: boolean;
+};
+
+export default function MessageComposer({
+  roomName,
+  replyTarget,
+  onSend,
+  onCancelReply,
+  onTyping,
+  disabled,
+}: Props) {
+  const [content, setContent] = useState("");
+  const [sending, setSending] = useState(false);
+  const typingTimeout = useRef<number | undefined>(undefined);
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  // Focus textarea when entering reply mode
+  useEffect(() => {
+    if (replyTarget) {
+      textareaRef.current?.focus();
+    }
+  }, [replyTarget?.id]);
+
+  const handleInput = useCallback(
+    (value: string) => {
+      setContent(value);
+      if (onTyping) {
+        onTyping(true);
+        clearTimeout(typingTimeout.current);
+        typingTimeout.current = window.setTimeout(() => onTyping(false), 5000);
+      }
+    },
+    [onTyping],
+  );
+
+  const handleSubmit = useCallback(async () => {
+    const text = content.trim();
+    if (!text || sending) return;
+
+    setSending(true);
+    try {
+      await onSend(text);
+      setContent("");
+      onTyping?.(false);
+      clearTimeout(typingTimeout.current);
+    } finally {
+      setSending(false);
+    }
+  }, [content, sending, onSend, onTyping]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        handleSubmit();
+      }
+    },
+    [handleSubmit],
+  );
+
+  const hasContent = content.trim().length > 0;
+
+  const replyAuthorName =
+    replyTarget?.sender.display_name ??
+    replyTarget?.sender.username ??
+    "Unknown";
+  const replyPreview =
+    replyTarget?.content.slice(0, 100) ?? "";
+
+  return (
+    <div className="shrink-0 px-4 pb-4 pt-1">
+      {/* Reply indicator */}
+      {replyTarget && (
+        <div className="mb-2 flex items-center gap-2 rounded-lg border border-primary/[0.08] bg-primary/[0.03] px-3 py-2">
+          <Reply className="size-4 shrink-0 text-primary/50" />
+          <div className="min-w-0 flex-1">
+            <p className="truncate text-[12px] font-medium text-primary/70">
+              Replying to {replyAuthorName}
+            </p>
+            <p className="truncate text-[11px] text-muted-foreground/50">
+              {replyPreview}
+            </p>
+          </div>
+          <Button
+            className="size-6 shrink-0 cursor-pointer text-muted-foreground/30 hover:text-foreground"
+            onClick={onCancelReply}
+            size="icon"
+            variant="ghost"
+          >
+            <X className="size-3.5" />
+          </Button>
+        </div>
+      )}
+
+      <div
+        className={cn(
+          "relative rounded-xl border bg-card shadow-sm transition-all duration-200",
+          "focus-within:border-primary/20 focus-within:shadow-md focus-within:ring-1 focus-within:ring-primary/[0.06]",
+          replyTarget ? "border-primary/[0.12]" : "border-border/50",
+        )}
+      >
+        <Textarea
+          aria-label={`Message #${roomName}`}
+          className={cn(
+            "min-h-[48px] max-h-48 resize-none border-0 bg-transparent px-4 py-3 pr-28 text-sm leading-relaxed shadow-none focus-visible:ring-0",
+            "placeholder:text-muted-foreground/30",
+          )}
+          disabled={disabled || sending}
+          onChange={(e) => handleInput(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder={
+            replyTarget
+              ? `Reply to ${replyAuthorName}…`
+              : `Message #${roomName}`
+          }
+          ref={textareaRef}
+          value={content}
+        />
+        <div className="absolute right-2 bottom-2 flex items-center gap-1">
+          <FileUploadButton disabled={disabled || sending} />
+          <Button
+            className={cn(
+              "size-8 rounded-lg transition-all duration-200",
+              hasContent
+                ? "scale-100 opacity-100"
+                : "scale-90 opacity-40",
+            )}
+            disabled={!hasContent || sending}
+            onClick={handleSubmit}
+            size="icon"
+            variant={hasContent ? "default" : "ghost"}
+          >
+            <Send className="size-[15px]" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/page/workspace/channel/file-upload.tsx b/src/page/workspace/channel/file-upload.tsx
new file mode 100644
index 0000000..4fcc870
--- /dev/null
+++ b/src/page/workspace/channel/file-upload.tsx
@@ -0,0 +1,184 @@
+import { useCallback, useRef, useState } from "react";
+import { Image, Loader2, Paperclip, X } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+type PendingFile = {
+  id: string;
+  name: string;
+  size: number;
+  preview?: string;
+  uploading: boolean;
+  progress: number;
+};
+
+type Props = {
+  disabled?: boolean;
+  onUploaded?: (url: string, filename: string) => void;
+  maxFiles?: number;
+  maxSize?: number;
+};
+
+export default function FileUploadButton({
+  disabled,
+  onUploaded,
+  maxFiles = 5,
+  maxSize = 50 * 1024 * 1024,
+}: Props) {
+  const [files, setFiles] = useState<PendingFile[]>([]);
+  const [error, setError] = useState("");
+  const inputRef = useRef<HTMLInputElement>(null);
+  const idCounter = useRef(0);
+
+  const handleFiles = useCallback(
+    (selected: FileList | null) => {
+      if (!selected || selected.length === 0) return;
+      setError("");
+
+      const newFiles: PendingFile[] = [];
+      for (let i = 0; i < selected.length; i++) {
+        const file = selected[i];
+        if (file.size > maxSize) {
+          setError(
+            `${file.name} exceeds the ${(maxSize / 1024 / 1024).toFixed(0)} MB limit`,
+          );
+          continue;
+        }
+        if (files.length + newFiles.length >= maxFiles) {
+          setError(`Maximum ${maxFiles} files allowed`);
+          break;
+        }
+        const id = `upload-${++idCounter.current}`;
+        const pending: PendingFile = {
+          id,
+          name: file.name,
+          size: file.size,
+          uploading: true,
+          progress: 0,
+          preview: file.type.startsWith("image/")
+            ? URL.createObjectURL(file)
+            : undefined,
+        };
+        newFiles.push(pending);
+        simulateUpload(file)
+          .then(() => {
+            setFiles((prev) => prev.filter((f) => f.id !== id));
+            onUploaded?.(`blob:${file.name}`, file.name);
+          })
+          .catch(() => {
+            setFiles((prev) =>
+              prev.map((f) =>
+                f.id === id ? { ...f, uploading: false, progress: 0 } : f,
+              ),
+            );
+            setError(`Failed to upload ${file.name}`);
+          });
+      }
+      setFiles((prev) => [...prev, ...newFiles]);
+      if (inputRef.current) inputRef.current.value = "";
+    },
+    [files.length, maxFiles, maxSize, onUploaded],
+  );
+
+  const removeFile = useCallback((id: string) => {
+    setFiles((prev) => {
+      const file = prev.find((f) => f.id === id);
+      if (file?.preview) URL.revokeObjectURL(file.preview);
+      return prev.filter((f) => f.id !== id);
+    });
+  }, []);
+
+  const formatSize = (bytes: number) => {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  };
+
+  return (
+    <div className="relative">
+      <input
+        accept="image/*,.pdf,.doc,.docx,.txt,.zip"
+        className="hidden"
+        multiple
+        onChange={(e) => handleFiles(e.target.files)}
+        ref={inputRef}
+        type="file"
+      />
+
+      <Button
+        className="size-8 cursor-pointer rounded-lg text-muted-foreground/40 hover:bg-accent/50 hover:text-muted-foreground"
+        disabled={disabled}
+        onClick={() => inputRef.current?.click()}
+        size="icon"
+        title="Attach file"
+        type="button"
+        variant="ghost"
+      >
+        <Paperclip className="size-[15px]" />
+      </Button>
+
+      {files.length > 0 && (
+        <div className="absolute bottom-full right-0 mb-2 w-72 space-y-1.5 rounded-xl border border-border/40 bg-card p-2.5 shadow-lg">
+          {files.map((file) => (
+            <div
+              className="flex items-center gap-2.5 rounded-lg p-1.5 transition-colors hover:bg-accent/30"
+              key={file.id}
+            >
+              {file.preview ? (
+                <img
+                  alt={file.name}
+                  className="size-9 shrink-0 rounded-lg object-cover ring-1 ring-border/40"
+                  src={file.preview}
+                />
+              ) : (
+                <div className="grid size-9 shrink-0 place-items-center rounded-lg bg-muted/50">
+                  <Image className="size-4 text-muted-foreground/40" />
+                </div>
+              )}
+              <div className="min-w-0 flex-1">
+                <p className="truncate text-[12px] font-medium text-foreground">
+                  {file.name}
+                </p>
+                <p className="text-[11px] text-muted-foreground/50">
+                  {formatSize(file.size)}
+                  {file.uploading && (
+                    <span className="ml-1.5 inline-flex items-center gap-1 text-primary/80">
+                      <Loader2 className="size-2.5 animate-spin" />
+                      uploading…
+                    </span>
+                  )}
+                </p>
+                {file.uploading && (
+                  <div className="mt-1.5 h-[3px] overflow-hidden rounded-full bg-muted/50">
+                    <div
+                      className="h-full rounded-full bg-primary/60 transition-all duration-500"
+                      style={{ width: `${Math.max(file.progress, 5)}%` }}
+                    />
+                  </div>
+                )}
+              </div>
+              <Button
+                className="size-6 shrink-0 cursor-pointer rounded-md text-muted-foreground/40 hover:bg-accent/50 hover:text-foreground"
+                onClick={() => removeFile(file.id)}
+                size="icon"
+                variant="ghost"
+              >
+                <X className="size-3" />
+              </Button>
+            </div>
+          ))}
+          {error && (
+            <p className="rounded-md bg-destructive/[0.04] px-2.5 py-1.5 text-[11px] text-destructive/80">
+              {error}
+            </p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+async function simulateUpload(_file: File): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 800 + Math.random() * 1200);
+  });
+}
diff --git a/src/page/workspace/channel/index.tsx b/src/page/workspace/channel/index.tsx
new file mode 100644
index 0000000..13023a1
--- /dev/null
+++ b/src/page/workspace/channel/index.tsx
@@ -0,0 +1,81 @@
+import { useState } from "react";
+import { useParams } from "react-router";
+import { useChannelState } from "./use-channel-state";
+import { ChannelHeader } from "./channel-header";
+import { ChannelThreadPanel } from "./channel-thread-panel";
+import RoomSettingsDialog from "./room-settings-dialog";
+import MessageView from "./message-view";
+
+export default function ChannelPage() {
+  const { roomId } = useParams();
+  const { state, actions } = useChannelState(roomId);
+  const [showThreads, setShowThreads] = useState(false);
+  const [showRoomSettings, setShowRoomSettings] = useState(false);
+
+  return (
+    <div className="relative flex h-full min-w-0 flex-col overflow-hidden">
+      {state.currentRoom ? (
+        <ChannelHeader
+          memberCount={undefined}
+          onToggleSettings={() => setShowRoomSettings(true)}
+          onToggleThreads={() => setShowThreads((v) => !v)}
+          room={state.currentRoom}
+          threads={state.threads}
+        />
+      ) : (
+        <div className="flex h-[52px] shrink-0 items-center border-b border-border/40 px-4">
+          {state.loadingRooms ? (
+            <span className="text-sm text-muted-foreground/40">Loading…</span>
+          ) : (
+            <span className="text-sm text-muted-foreground/40">
+              Select a channel
+            </span>
+          )}
+        </div>
+      )}
+
+      <MessageView
+        currentUserId={state.currentUserId}
+        hasMore={state.hasMore}
+        loading={state.loadingMessages}
+        messages={state.messages}
+        onDelete={actions.handleDeleteMessage}
+        onEdit={actions.handleEditMessage}
+        onLoadMore={actions.handleLoadMore}
+        onPinToggle={actions.handlePinToggle}
+        onReactionToggle={actions.handleReactionToggle}
+        onSend={actions.handleSend}
+        onStartThread={actions.handleStartThread}
+        onTyping={actions.handleTyping}
+        roomId={roomId ?? ""}
+        roomName={state.currentRoom?.name ?? ""}
+        streamingMessages={state.streamingMessages}
+        typingText={state.typingText}
+      />
+
+      {roomId && (
+        <ChannelThreadPanel
+          onClose={() => setShowThreads(false)}
+          open={showThreads}
+          roomId={roomId}
+          threads={state.threads}
+        />
+      )}
+
+      {roomId && state.currentRoom && (
+        <RoomSettingsDialog
+          categories={state.categories}
+          categoryId={state.currentRoom.category ?? null}
+          isPrivate={state.currentRoom.is_private}
+          onDeleted={() => {}}
+          onOpenChange={setShowRoomSettings}
+          onUpdated={() => {}}
+          open={showRoomSettings}
+          roomId={roomId}
+          roomName={state.currentRoom.name}
+          topic={state.currentRoom.topic}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/src/page/workspace/channel/invite-dialog.tsx b/src/page/workspace/channel/invite-dialog.tsx
new file mode 100644
index 0000000..20d4f2c
--- /dev/null
+++ b/src/page/workspace/channel/invite-dialog.tsx
@@ -0,0 +1,145 @@
+import { useCallback, useState } from "react";
+import { Check, Copy, Link, Loader2, UserPlus } from "lucide-react";
+import { api } from "@/client";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { useToast } from "@/hooks/use-toast";
+
+type Props = {
+  workspaceId: string;
+  roomId?: string;
+  children: React.ReactNode;
+};
+
+export default function InviteDialog({ workspaceId, roomId, children }: Props) {
+  const [open, setOpen] = useState(false);
+  const [inviteLink, setInviteLink] = useState("");
+  const [generating, setGenerating] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const { toast } = useToast();
+
+  const handleGenerate = useCallback(async () => {
+    setGenerating(true);
+    try {
+      const res = await api.post<{ data?: { code: string } }>(
+        "/api/v1/ws/invites",
+        {
+          workspace: workspaceId,
+          room: roomId ?? null,
+        },
+      );
+      const code = res.data?.data?.code;
+      if (code) {
+        const link = `${window.location.origin}/join/${code}`;
+        setInviteLink(link);
+        await navigator.clipboard.writeText(link);
+        setCopied(true);
+        toast({
+          title: "Invite link copied",
+          description: "Share this link with your team",
+        });
+        setTimeout(() => setCopied(false), 2000);
+      }
+    } catch {
+      toast({
+        title: "Error",
+        description: "Failed to create invite",
+        variant: "destructive",
+      });
+    } finally {
+      setGenerating(false);
+    }
+  }, [workspaceId, roomId, toast]);
+
+  const handleCopy = useCallback(async () => {
+    if (!inviteLink) return;
+    await navigator.clipboard.writeText(inviteLink);
+    setCopied(true);
+    toast({ title: "Copied!" });
+    setTimeout(() => setCopied(false), 2000);
+  }, [inviteLink, toast]);
+
+  return (
+    <Dialog onOpenChange={setOpen} open={open}>
+      <DialogTrigger>{children}</DialogTrigger>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2 text-base">
+            <UserPlus className="size-5 text-primary/60" />
+            Invite People
+          </DialogTitle>
+          <DialogDescription>
+            Generate an invite link to share with your team.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <Label className="text-[13px]" htmlFor="invite-link">
+              Invite link
+            </Label>
+            {inviteLink ? (
+              <div className="flex items-center gap-2">
+                <Input
+                  className="flex-1 font-mono text-[12px]"
+                  id="invite-link"
+                  readOnly
+                  value={inviteLink}
+                />
+                <Button
+                  className="shrink-0 cursor-pointer"
+                  onClick={handleCopy}
+                  size="icon"
+                  variant="outline"
+                >
+                  {copied ? (
+                    <Check className="size-4 text-emerald-500" />
+                  ) : (
+                    <Copy className="size-4" />
+                  )}
+                </Button>
+              </div>
+            ) : (
+              <div className="flex items-center gap-3 rounded-lg border border-dashed border-border/40 px-4 py-7">
+                <Link className="size-5 shrink-0 text-muted-foreground/30" />
+                <p className="text-sm text-muted-foreground/50">
+                  Click generate to create an invite link.
+                </p>
+              </div>
+            )}
+          </div>
+        </div>
+
+        <DialogFooter>
+          <Button
+            className="cursor-pointer"
+            onClick={() => setOpen(false)}
+            variant="outline"
+          >
+            Close
+          </Button>
+          <Button
+            className="cursor-pointer"
+            disabled={generating}
+            onClick={handleGenerate}
+          >
+            {generating && (
+              <Loader2 className="mr-2 size-4 animate-spin" />
+            )}
+            Generate Invite
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/page/workspace/channel/message-item.tsx b/src/page/workspace/channel/message-item.tsx
new file mode 100644
index 0000000..bfe8f2b
--- /dev/null
+++ b/src/page/workspace/channel/message-item.tsx
@@ -0,0 +1,470 @@
+import { useCallback, useState } from "react";
+import {
+  Pencil,
+  Pin,
+  PinOff,
+  SmilePlus,
+  Trash2,
+  MessageSquarePlus,
+  Copy,
+  MoreHorizontal,
+  CornerDownRight,
+  Reply,
+} from "lucide-react";
+import { api } from "@/client";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Textarea } from "@/components/ui/textarea";
+import type { MessageNewService } from "@/socket";
+
+export function formatTime(iso: string) {
+  const d = new Date(iso);
+  return d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}
+
+export function formatDate(iso: string) {
+  const d = new Date(iso);
+  const now = new Date();
+  if (d.toDateString() === now.toDateString()) return "Today";
+  const yesterday = new Date(now);
+  yesterday.setDate(yesterday.getDate() - 1);
+  if (d.toDateString() === yesterday.toDateString()) return "Yesterday";
+  return d.toLocaleDateString([], {
+    month: "long",
+    day: "numeric",
+    year: d.getFullYear() !== now.getFullYear() ? "numeric" : undefined,
+  });
+}
+
+export function DateDivider({ date }: { date: string }) {
+  return (
+    <div className="flex items-center gap-3 px-4 py-4">
+      <div className="h-px flex-1 bg-gradient-to-r from-transparent via-border/50 to-transparent" />
+      <span className="shrink-0 rounded-full bg-muted/40 px-3 py-0.5 text-[11px] font-medium text-muted-foreground/50">
+        {date}
+      </span>
+      <div className="h-px flex-1 bg-gradient-to-r from-transparent via-border/50 to-transparent" />
+    </div>
+  );
+}
+
+type Props = {
+  message: MessageNewService;
+  messages?: MessageNewService[];
+  showHeader: boolean;
+  isCompact: boolean;
+  currentUserId?: string;
+  roomId: string;
+  onReply?: (message: MessageNewService) => void;
+  onPinToggle?: (messageId: string, pinned: boolean) => void;
+  onDelete?: (messageId: string) => void;
+  onEdit?: (messageId: string, content: string) => void;
+  onStartThread?: (messageId: string, seq: number) => void;
+  onReactionToggle?: (messageId: string, emoji: string, add: boolean) => void;
+};
+
+export default function MessageItem({
+  message,
+  messages,
+  showHeader,
+  isCompact,
+  currentUserId,
+  roomId,
+  onReply,
+  onPinToggle,
+  onDelete,
+  onEdit,
+  onStartThread,
+  onReactionToggle,
+}: Props) {
+  const [editing, setEditing] = useState(false);
+  const [editContent, setEditContent] = useState(message.content);
+  const [saving, setSaving] = useState(false);
+
+  const name =
+    message.sender.display_name || message.sender.username || "Unknown";
+  const initial = workspaceInitial(name);
+  const colorClass = workspaceColor(name);
+  const isOwn = currentUserId && message.sender.id === currentUserId;
+  const isPinned = (message as Record<string, unknown>).pinned as
+    | boolean
+    | undefined;
+
+  // Look up the replied-to message from the local message list
+  const repliedMessage = message.in_reply_to
+    ? messages?.find((m) => m.id === message.in_reply_to)
+    : undefined;
+  const replyAuthor =
+    repliedMessage?.sender.display_name ??
+    repliedMessage?.sender.username ??
+    undefined;
+  const replyPreview = repliedMessage?.content.slice(0, 80);
+
+  const handleReaction = useCallback(
+    (emoji: string) => {
+      const existing = message.reactions?.find(
+        (r) => r.emoji === emoji && r.reacted_by_me,
+      );
+      onReactionToggle?.(message.id, emoji, !existing);
+      if (existing) {
+        api
+          .delete(`/api/v1/ws/rooms/${roomId}/reactions`, {
+            data: { message: message.id, emoji },
+          })
+          .catch(() => {
+            onReactionToggle?.(message.id, emoji, true);
+          });
+      } else {
+        api
+          .post(`/api/v1/ws/rooms/${roomId}/reactions`, {
+            message: message.id,
+            emoji,
+          })
+          .catch(() => {
+            onReactionToggle?.(message.id, emoji, false);
+          });
+      }
+    },
+    [message.id, message.reactions, roomId, onReactionToggle],
+  );
+
+  const handleSaveEdit = useCallback(async () => {
+    const trimmed = editContent.trim();
+    if (!trimmed || trimmed === message.content) {
+      setEditing(false);
+      setEditContent(message.content);
+      return;
+    }
+    setSaving(true);
+    try {
+      await api.patch(`/api/v1/ws/messages/${message.id}`, {
+        content: trimmed,
+      });
+      onEdit?.(message.id, trimmed);
+      setEditing(false);
+    } catch {
+      // ignore
+    } finally {
+      setSaving(false);
+    }
+  }, [editContent, message.content, message.id, onEdit]);
+
+  const handleEditKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Escape") {
+        setEditing(false);
+        setEditContent(message.content);
+      } else if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        handleSaveEdit();
+      }
+    },
+    [handleSaveEdit, message.content],
+  );
+
+  return (
+    <div
+      className={cn(
+        "group relative flex gap-3 transition-colors duration-150",
+        isCompact
+          ? "items-start px-4 py-[1px] hover:bg-accent/[0.03]"
+          : "items-start px-4 py-1.5 hover:bg-accent/[0.03]",
+      )}
+    >
+      {isCompact ? (
+        <div className="w-9 shrink-0 pt-0.5 text-center">
+          <span className="text-[10px] text-muted-foreground/0 transition-opacity duration-150 group-hover:text-muted-foreground/40">
+            {formatTime(message.send_at)}
+          </span>
+        </div>
+      ) : (
+        <div
+          className={cn(
+            "grid size-9 shrink-0 place-items-center rounded-full bg-gradient-to-br text-sm font-semibold text-white shadow-sm",
+            colorClass,
+          )}
+        >
+          {message.sender.avatar_url ? (
+            <img
+              alt={name}
+              className="size-full rounded-full object-cover"
+              src={message.sender.avatar_url}
+            />
+          ) : (
+            initial
+          )}
+        </div>
+      )}
+
+      <div className="min-w-0 flex-1">
+        {!isCompact && showHeader && (
+          <div className="flex items-baseline gap-2">
+            <span className="cursor-pointer text-sm font-semibold text-foreground transition-colors hover:text-primary">
+              {name}
+            </span>
+            <span className="text-[11px] text-muted-foreground/40">
+              {formatTime(message.send_at)}
+            </span>
+            {message.sender_type !== "user" && (
+              <span className="rounded-full bg-primary/[0.06] px-1.5 py-[1px] text-[10px] font-medium text-primary/70">
+                {message.sender_type}
+              </span>
+            )}
+            {isPinned && (
+              <span className="text-amber-500/70" title="Pinned">
+                <Pin className="size-3" />
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Reply context indicator */}
+        {message.in_reply_to && (
+          <div
+            className={cn(
+              "mb-0.5 flex items-center gap-1.5 rounded rounded-r-md border-l-2 border-primary/30 bg-muted/[0.15] px-2 py-0.5 text-left",
+              repliedMessage && "cursor-pointer transition-colors hover:bg-muted/[0.3]",
+            )}
+            onClick={() => {
+              if (repliedMessage) onReply?.(repliedMessage);
+            }}
+            title={replyPreview ? `Replying to: ${replyPreview}` : "Replying to a message"}
+            role={repliedMessage ? "button" : undefined}
+          >
+            <CornerDownRight className="size-3 shrink-0 text-primary/40" />
+            {replyAuthor ? (
+              <span className="truncate text-[11px] font-medium text-primary/60">
+                {replyAuthor}
+              </span>
+            ) : (
+              <span className="text-[11px] text-muted-foreground/40">
+                Original message
+              </span>
+            )}
+            {replyPreview && (
+              <span className="truncate text-[11px] text-muted-foreground/35">
+                {replyPreview}
+              </span>
+            )}
+          </div>
+        )}
+
+        {editing ? (
+          <div className="mt-1 space-y-2">
+            <Textarea
+              autoFocus
+              className="min-h-[60px] resize-none rounded-lg text-sm"
+              disabled={saving}
+              onBlur={handleSaveEdit}
+              onChange={(e) => setEditContent(e.target.value)}
+              onKeyDown={handleEditKeyDown}
+              value={editContent}
+            />
+            <div className="flex items-center gap-2 text-[11px] text-muted-foreground/40">
+              <span>Esc to cancel · Enter to save</span>
+            </div>
+          </div>
+        ) : message.content_type === "text" || !message.content_type ? (
+          <p className="whitespace-pre-wrap break-words text-[14px] leading-[1.6] text-foreground/90">
+            {message.content}
+          </p>
+        ) : (
+          <p className="whitespace-pre-wrap break-words text-[14px] text-foreground/90">
+            <span className="rounded bg-muted/50 px-1.5 py-[1px] text-[10px] font-medium uppercase text-muted-foreground/60">
+              {message.content_type}
+            </span>{" "}
+            {message.content}
+          </p>
+        )}
+
+        {message.reactions && message.reactions.length > 0 && (
+          <div className="mt-1.5 flex flex-wrap gap-1">
+            {message.reactions.map((r) => (
+              <button
+                className={cn(
+                  "inline-flex cursor-pointer items-center gap-1 rounded-full border px-2 py-[1px] text-xs transition-all duration-150",
+                  r.reacted_by_me
+                    ? "border-primary/20 bg-primary/[0.06] text-primary hover:bg-primary/[0.1]"
+                    : "border-border/40 bg-muted/30 text-muted-foreground/70 hover:border-border/60 hover:bg-accent/40",
+                )}
+                key={r.emoji}
+                onClick={() => handleReaction(r.emoji)}
+                title={r.reacted_by_me ? "Click to remove" : "Click to add"}
+              >
+                <span>{r.emoji}</span>
+                <span className="text-[11px] tabular-nums">{r.count}</span>
+              </button>
+            ))}
+            <ReactionPicker onSelect={(emoji) => handleReaction(emoji)}>
+              <button className="inline-flex size-6 cursor-pointer items-center justify-center rounded-full border border-dashed border-border/40 text-muted-foreground/30 opacity-0 transition-all duration-150 hover:border-primary/30 hover:text-primary/60 group-hover:opacity-100">
+                <SmilePlus className="size-3" />
+              </button>
+            </ReactionPicker>
+          </div>
+        )}
+      </div>
+
+      <div className="absolute -top-3 right-3 z-10 flex items-center gap-[1px] rounded-lg border border-border/40 bg-background/95 px-0.5 py-0.5 shadow-md backdrop-blur-sm opacity-0 transition-all duration-150 group-hover:opacity-100">
+        <ReactionPicker onSelect={(emoji) => handleReaction(emoji)}>
+          <Button
+            className="size-7 cursor-pointer rounded-md"
+            size="icon"
+            title="Add reaction"
+            variant="ghost"
+          >
+            <SmilePlus className="size-3.5" />
+          </Button>
+        </ReactionPicker>
+
+        <Button
+          className="size-7 cursor-pointer rounded-md"
+          onClick={() => onReply?.(message)}
+          size="icon"
+          title="Reply"
+          variant="ghost"
+        >
+          <Reply className="size-3.5" />
+        </Button>
+
+        <Button
+          className="size-7 cursor-pointer rounded-md"
+          onClick={() => onStartThread?.(message.id, message.seq)}
+          size="icon"
+          title="Start thread"
+          variant="ghost"
+        >
+          <MessageSquarePlus className="size-3.5" />
+        </Button>
+
+        <DropdownMenu>
+          <DropdownMenuTrigger>
+            <Button
+              className="size-7 cursor-pointer rounded-md"
+              size="icon"
+              title="More"
+              variant="ghost"
+            >
+              <MoreHorizontal className="size-3.5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-44">
+            <DropdownMenuItem
+              className="cursor-pointer text-[13px]"
+              onClick={() => onReply?.(message)}
+            >
+              <Reply className="mr-2 size-4" />
+              Reply
+            </DropdownMenuItem>
+
+            <DropdownMenuItem
+              className="cursor-pointer text-[13px]"
+              onClick={() => {
+                navigator.clipboard.writeText(message.content);
+              }}
+            >
+              <Copy className="mr-2 size-4" />
+              Copy text
+            </DropdownMenuItem>
+
+            {isOwn && (
+              <DropdownMenuItem
+                className="cursor-pointer text-[13px]"
+                onClick={() => {
+                  setEditContent(message.content);
+                  setEditing(true);
+                }}
+              >
+                <Pencil className="mr-2 size-4" />
+                Edit message
+              </DropdownMenuItem>
+            )}
+
+            {isOwn && (
+              <DropdownMenuItem
+                className="cursor-pointer text-[13px] text-destructive focus:text-destructive"
+                onClick={() => onDelete?.(message.id)}
+              >
+                <Trash2 className="mr-2 size-4" />
+                Delete message
+              </DropdownMenuItem>
+            )}
+
+            <DropdownMenuSeparator />
+
+            <DropdownMenuItem
+              className="cursor-pointer text-[13px]"
+              onClick={() => onPinToggle?.(message.id, !isPinned)}
+            >
+              {isPinned ? (
+                <>
+                  <PinOff className="mr-2 size-4" />
+                  Unpin message
+                </>
+              ) : (
+                <>
+                  <Pin className="mr-2 size-4" />
+                  Pin message
+                </>
+              )}
+            </DropdownMenuItem>
+
+            <DropdownMenuItem
+              className="cursor-pointer text-[13px]"
+              onClick={() => onStartThread?.(message.id, message.seq)}
+            >
+              <MessageSquarePlus className="mr-2 size-4" />
+              Start thread
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
+    </div>
+  );
+}
+
+const REACTIONS_PALETTE = [
+  "👍", "👎", "😄", "🎉", "😕", "❤️", "🚀", "👀",
+  "✅", "❌", "🔥", "💯", "🤔", "🙌", "😢", "🤯",
+];
+
+function ReactionPicker({
+  children,
+  onSelect,
+}: {
+  children: React.ReactNode;
+  onSelect: (emoji: string) => void;
+}) {
+  return (
+    <Popover>
+      <PopoverTrigger>{children}</PopoverTrigger>
+      <PopoverContent
+        align="start"
+        className="w-auto p-2"
+        side="top"
+        sideOffset={8}
+      >
+        <div className="grid grid-cols-8 gap-0.5">
+          {REACTIONS_PALETTE.map((emoji) => (
+            <button
+              className="grid size-8 cursor-pointer place-items-center rounded-md text-lg transition-all duration-150 hover:scale-110 hover:bg-accent/50"
+              key={emoji}
+              onClick={() => onSelect(emoji)}
+              title={emoji}
+            >
+              {emoji}
+            </button>
+          ))}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/src/page/workspace/channel/message-view.tsx b/src/page/workspace/channel/message-view.tsx
new file mode 100644
index 0000000..ef7c35b
--- /dev/null
+++ b/src/page/workspace/channel/message-view.tsx
@@ -0,0 +1,350 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { Loader2, MessageSquare, ChevronDown, Pin } from "lucide-react";
+import type { MessageNewService } from "@/socket";
+import MessageItem, { DateDivider, formatDate } from "./message-item";
+import MessageComposer from "./composer";
+
+type Props = {
+  roomId: string;
+  roomName: string;
+  currentUserId?: string;
+  messages: MessageNewService[];
+  loading: boolean;
+  hasMore: boolean;
+  onLoadMore: () => void;
+  onSend: (content: string, inReplyTo?: string) => Promise<void>;
+  onTyping?: (typing: boolean) => void;
+  onPinToggle?: (messageId: string, pinned: boolean) => void;
+  onDelete?: (messageId: string) => void;
+  onEdit?: (messageId: string, content: string) => void;
+  onStartThread?: (messageId: string, seq: number) => void;
+  onReactionToggle?: (
+    messageId: string,
+    emoji: string,
+    add: boolean,
+  ) => void;
+  streamingMessages?: Map<
+    string,
+    { content: string; displayName?: string }
+  >;
+  typingText?: string | null;
+};
+
+function shouldShowHeader(
+  current: MessageNewService,
+  prev?: MessageNewService,
+): boolean {
+  if (!prev) return true;
+  if (current.sender.id !== prev.sender.id) return true;
+  const curTime = current.send_at ? new Date(current.send_at).getTime() : 0;
+  const prvTime = prev.send_at ? new Date(prev.send_at).getTime() : 0;
+  if (!curTime || !prvTime) return true;
+  return curTime - prvTime > 5 * 60 * 1000;
+}
+
+function shouldShowDate(
+  current: MessageNewService,
+  prev?: MessageNewService,
+): boolean {
+  if (!prev) return true;
+  const cur = current.send_at ? new Date(current.send_at) : new Date();
+  const prv = prev.send_at ? new Date(prev.send_at) : new Date();
+  if (isNaN(cur.getTime()) || isNaN(prv.getTime())) return true;
+  return cur.toDateString() !== prv.toDateString();
+}
+
+type RenderedItem =
+  | { type: "loading" | "more_loading" | "notice_beginning" | "notice_scroll" }
+  | { type: "date"; date: string; id: string }
+  | { type: "message"; msg: MessageNewService; isCompact: boolean; showHeader: boolean };
+
+export default function MessageView({
+  roomId,
+  roomName,
+  currentUserId,
+  messages,
+  loading,
+  hasMore,
+  onLoadMore,
+  onSend,
+  onTyping,
+  onPinToggle,
+  onDelete,
+  onEdit,
+  onStartThread,
+  onReactionToggle,
+  streamingMessages = new Map(),
+  typingText,
+}: Props) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const [atBottom, setAtBottom] = useState(true);
+  const [newMsgCount, setNewMsgCount] = useState(0);
+  const prevMsgCountRef = useRef(0);
+  const [replyTarget, setReplyTarget] = useState<MessageNewService | null>(null);
+
+  const pinnedMessages = useMemo(
+    () => messages.filter((m) => (m as Record<string, unknown>).pinned),
+    [messages],
+  );
+
+  const renderedItems = useMemo<RenderedItem[]>(() => {
+    const result: RenderedItem[] = [];
+
+    if (loading && messages.length === 0) {
+      result.push({ type: "loading" });
+      return result;
+    }
+
+    if (!loading && !hasMore) {
+      result.push({ type: "notice_beginning" });
+    } else if (!loading && hasMore) {
+      result.push({ type: "notice_scroll" });
+    } else if (loading) {
+      result.push({ type: "more_loading" });
+    }
+
+    let prevMsg: MessageNewService | undefined;
+
+    for (const msg of messages) {
+      if (shouldShowDate(msg, prevMsg)) {
+        result.push({ type: "date", date: msg.send_at, id: `d-${msg.id}` });
+        prevMsg = undefined;
+      }
+
+      const showHeader = shouldShowHeader(msg, prevMsg);
+      result.push({
+        type: "message",
+        msg,
+        isCompact: !showHeader,
+        showHeader,
+      });
+      prevMsg = msg;
+    }
+
+    return result;
+  }, [messages, loading, hasMore]);
+
+  const messageCount = useMemo(
+    () => renderedItems.filter((i) => i.type === "message").length,
+    [renderedItems],
+  );
+
+  useEffect(() => {
+    prevMsgCountRef.current = 0;
+    setNewMsgCount(0);
+    bottomRef.current?.scrollIntoView();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [roomId]);
+
+  useEffect(() => {
+    const prev = prevMsgCountRef.current;
+    prevMsgCountRef.current = messageCount;
+
+    if (messageCount > prev && prev > 0 && !loading) {
+      if (atBottom) {
+        bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+        setNewMsgCount(0);
+      } else {
+        setNewMsgCount((c) => c + (messageCount - prev));
+      }
+    }
+  }, [messageCount, loading, atBottom]);
+
+  const handleScroll = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+
+    const threshold = 80;
+    const isAtBottom =
+      el.scrollHeight - el.scrollTop - el.clientHeight < threshold;
+    setAtBottom(isAtBottom);
+    if (isAtBottom) setNewMsgCount(0);
+
+    if (el.scrollTop < threshold && hasMore && !loading) {
+      onLoadMore();
+    }
+  }, [hasMore, loading, onLoadMore]);
+
+  const handleScrollToBottom = useCallback(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+    setNewMsgCount(0);
+    setAtBottom(true);
+  }, []);
+
+  if (!roomId) {
+    return (
+      <div className="flex min-h-0 flex-1 flex-col items-center justify-center">
+        <div className="text-center">
+          <div className="mx-auto grid size-20 place-items-center rounded-2xl bg-muted/20 ring-1 ring-border/30">
+            <MessageSquare className="size-8 text-muted-foreground/15" />
+          </div>
+          <h3 className="mt-5 text-lg font-semibold text-foreground">
+            Select a channel
+          </h3>
+          <p className="mt-1.5 text-sm text-muted-foreground/40">
+            Choose a channel from the sidebar to start chatting
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {pinnedMessages.length > 0 && (
+        <div className="flex shrink-0 items-center gap-2 border-b border-border/30 bg-amber-500/[0.03] px-4 py-1.5">
+          <Pin className="size-3 text-amber-500/60" />
+          <span className="truncate text-[12px] text-muted-foreground/60">
+            {pinnedMessages.length} pinned message
+            {pinnedMessages.length > 1 ? "s" : ""}
+          </span>
+        </div>
+      )}
+
+      <div className="relative min-h-0 flex-1">
+        <div
+          ref={scrollRef}
+          className="absolute inset-0 overflow-y-auto overscroll-contain scroll-smooth"
+          onScroll={handleScroll}
+        >
+          {renderedItems.map((item) => {
+            switch (item.type) {
+              case "loading":
+                return (
+                  <div
+                    key="loading"
+                    className="flex items-center justify-center py-20"
+                  >
+                    <Loader2 className="size-5 animate-spin text-muted-foreground/30" />
+                  </div>
+                );
+              case "more_loading":
+                return (
+                  <div key="more_loading" className="flex justify-center py-3">
+                    <Loader2 className="size-4 animate-spin text-muted-foreground/30" />
+                  </div>
+                );
+              case "notice_beginning":
+                return (
+                  <div key="notice_beginning" className="flex items-center gap-3 px-4 py-5">
+                    <div className="h-px flex-1 bg-gradient-to-r from-transparent via-border/40 to-transparent" />
+                    <span className="shrink-0 text-[11px] font-medium text-muted-foreground/30">
+                      Beginning of #{roomName}
+                    </span>
+                    <div className="h-px flex-1 bg-gradient-to-r from-transparent via-border/40 to-transparent" />
+                  </div>
+                );
+              case "notice_scroll":
+                return (
+                  <div
+                    key="notice_scroll"
+                    className="py-3 text-center text-[11px] text-muted-foreground/30"
+                  >
+                    Scroll up for older messages
+                  </div>
+                );
+              case "date":
+                return <DateDivider key={item.id} date={formatDate(item.date)} />;
+              case "message":
+                return (
+                  <MessageItem
+                    currentUserId={currentUserId}
+                    isCompact={item.isCompact}
+                    key={item.msg.id}
+                    message={item.msg}
+                    messages={messages}
+                    onDelete={onDelete}
+                    onEdit={onEdit}
+                    onPinToggle={onPinToggle}
+                    onReactionToggle={onReactionToggle}
+                    onStartThread={onStartThread}
+                    onReply={(msg) => setReplyTarget(msg)}
+                    roomId={roomId}
+                    showHeader={item.showHeader}
+                  />
+                );
+              default:
+                return null;
+            }
+          })}
+
+          {Array.from(streamingMessages.entries()).map(([id, stream]) => (
+            <div className="group relative flex gap-3 px-4 py-1.5" key={`stream-${id}`}>
+              <div className="grid size-9 shrink-0 place-items-center rounded-full bg-gradient-to-br from-primary/20 to-primary/5">
+                <Loader2 className="size-4 animate-spin text-primary/60" />
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="flex items-baseline gap-2">
+                  <span className="text-sm font-semibold text-foreground">
+                    {stream.displayName ?? "AI"}
+                  </span>
+                  <span className="rounded-full bg-primary/[0.06] px-1.5 py-[1px] text-[10px] font-medium text-primary/70">
+                    streaming
+                  </span>
+                </div>
+                {stream.content ? (
+                  <p className="mt-0.5 whitespace-pre-wrap break-words text-sm text-foreground/80">
+                    {stream.content}
+                    <span className="ml-0.5 inline-block h-3.5 w-0.5 animate-pulse bg-primary/40 align-text-bottom" />
+                  </p>
+                ) : (
+                  <div className="mt-1.5 flex gap-1">
+                    <span className="inline-block size-1.5 animate-bounce rounded-full bg-muted-foreground/20 [animation-delay:0ms]" />
+                    <span className="inline-block size-1.5 animate-bounce rounded-full bg-muted-foreground/20 [animation-delay:150ms]" />
+                    <span className="inline-block size-1.5 animate-bounce rounded-full bg-muted-foreground/20 [animation-delay:300ms]" />
+                  </div>
+                )}
+              </div>
+            </div>
+          ))}
+
+          <div ref={bottomRef} />
+        </div>
+
+        {newMsgCount > 0 && (
+          <button
+            className="absolute bottom-3 left-1/2 z-20 flex -translate-x-1/2 cursor-pointer items-center gap-1.5 rounded-full bg-primary px-4 py-1.5 text-xs font-medium text-primary-foreground shadow-lg transition-all duration-200 hover:bg-primary/90 hover:shadow-xl"
+            onClick={handleScrollToBottom}
+          >
+            <ChevronDown className="size-3.5" />
+            {newMsgCount} new message{newMsgCount > 1 ? "s" : ""}
+          </button>
+        )}
+      </div>
+
+      {typingText && (
+        <div
+          aria-live="polite"
+          className="flex h-6 shrink-0 items-center gap-1.5 px-4"
+        >
+          <span className="flex gap-0.5">
+            <span className="inline-block size-1 animate-bounce rounded-full bg-muted-foreground/30 [animation-delay:0ms]" />
+            <span className="inline-block size-1 animate-bounce rounded-full bg-muted-foreground/30 [animation-delay:150ms]" />
+            <span className="inline-block size-1 animate-bounce rounded-full bg-muted-foreground/30 [animation-delay:300ms]" />
+          </span>
+          <span className="truncate text-[11px] text-muted-foreground/50">
+            {typingText}
+          </span>
+        </div>
+      )}
+
+      <MessageComposer
+        onCancelReply={() => setReplyTarget(null)}
+        onSend={(content) => {
+          onSend(content, replyTarget?.id);
+          setReplyTarget(null);
+        }}
+        onTyping={onTyping}
+        replyTarget={replyTarget}
+        roomName={roomName}
+      />
+    </div>
+  );
+}
diff --git a/src/page/workspace/channel/room-create-dialog.tsx b/src/page/workspace/channel/room-create-dialog.tsx
new file mode 100644
index 0000000..f27631d
--- /dev/null
+++ b/src/page/workspace/channel/room-create-dialog.tsx
@@ -0,0 +1,220 @@
+import { useCallback, useState } from "react";
+import { Hash, Loader2, Plus } from "lucide-react";
+import { api } from "@/client";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Switch } from "@/components/ui/switch";
+import type { Category } from "./channel-sidebar";
+
+type Props = {
+  workspaceId: string;
+  categories: Category[];
+  children: React.ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  onCreated?: () => void;
+};
+
+export default function RoomCreateDialog({
+  workspaceId,
+  categories,
+  children,
+  open: controlledOpen,
+  onOpenChange: controlledOnOpenChange,
+  onCreated,
+}: Props) {
+  const [internalOpen, setInternalOpen] = useState(false);
+  const open = controlledOpen ?? internalOpen;
+  const setOpen = controlledOnOpenChange ?? setInternalOpen;
+  const [name, setName] = useState("");
+  const [isPublic, setIsPublic] = useState(true);
+  const [categoryId, setCategoryId] = useState("");
+  const [newCategoryName, setNewCategoryName] = useState("");
+  const [creatingCategory, setCreatingCategory] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  const handleCreateCategory = useCallback(async () => {
+    const trimmed = newCategoryName.trim();
+    if (!trimmed) return;
+    setCreatingCategory(true);
+    try {
+      await api.post(`/api/v1/ws/workspaces/${workspaceId}/categories`, {
+        name: trimmed,
+      });
+      setNewCategoryName("");
+      onCreated?.();
+    } catch {
+      setError("Failed to create category");
+    } finally {
+      setCreatingCategory(false);
+    }
+  }, [newCategoryName, workspaceId, onCreated]);
+
+  const handleCreate = useCallback(async () => {
+    const trimmed = name.trim();
+    if (!trimmed) {
+      setError("Channel name is required");
+      return;
+    }
+    setSaving(true);
+    setError("");
+    try {
+      await api.post("/api/v1/ws/rooms", {
+        workspace: workspaceId,
+        room_name: trimmed,
+        public: isPublic,
+        category: categoryId || null,
+      });
+      setName("");
+      setIsPublic(true);
+      setCategoryId("");
+      setNewCategoryName("");
+      setOpen(false);
+      onCreated?.();
+    } catch {
+      setError("Failed to create channel");
+    } finally {
+      setSaving(false);
+    }
+  }, [name, isPublic, categoryId, workspaceId, onCreated]);
+
+  return (
+    <Dialog onOpenChange={setOpen} open={open}>
+      <DialogTrigger>{children}</DialogTrigger>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2 text-base">
+            <Hash className="size-5 text-primary/60" />
+            Create Channel
+          </DialogTitle>
+          <DialogDescription>
+            Create a new channel in this workspace.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <Label className="text-[13px]" htmlFor="channel-name">
+              Channel name
+            </Label>
+            <Input
+              autoFocus
+              id="channel-name"
+              maxLength={100}
+              onChange={(e) => {
+                setName(e.target.value);
+                setError("");
+              }}
+              placeholder="e.g. general, random"
+              value={name}
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label className="text-[13px]">Category</Label>
+            {categories.length > 0 ? (
+              <select
+                className="flex h-9 w-full cursor-pointer rounded-md border border-border/40 bg-transparent px-3 py-1 text-sm shadow-sm transition-colors focus:border-primary/30 focus:outline-none"
+                onChange={(e) => setCategoryId(e.target.value)}
+                value={categoryId}
+              >
+                <option value="">No category</option>
+                {categories.map((cat) => (
+                  <option key={cat.id} value={cat.id}>
+                    {cat.name}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <p className="text-xs text-muted-foreground/40">
+                No categories yet — create one below
+              </p>
+            )}
+
+            <div className="flex gap-2">
+              <Input
+                className="h-8 flex-1 text-sm"
+                onChange={(e) => setNewCategoryName(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") {
+                    e.preventDefault();
+                    handleCreateCategory();
+                  }
+                }}
+                placeholder="New category name…"
+                value={newCategoryName}
+              />
+              <Button
+                className="h-8 shrink-0 cursor-pointer"
+                disabled={!newCategoryName.trim() || creatingCategory}
+                onClick={handleCreateCategory}
+                size="sm"
+                variant="outline"
+              >
+                {creatingCategory ? (
+                  <Loader2 className="size-3.5 animate-spin" />
+                ) : (
+                  <Plus className="size-3.5" />
+                )}
+              </Button>
+            </div>
+          </div>
+
+          <div className="flex items-center justify-between rounded-lg border border-border/30 px-3 py-2.5">
+            <div className="space-y-0.5">
+              <Label
+                className="text-[13px] font-medium"
+                htmlFor="channel-public"
+              >
+                Public channel
+              </Label>
+              <p className="text-[11px] text-muted-foreground/40">
+                Anyone in the workspace can join
+              </p>
+            </div>
+            <Switch
+              checked={isPublic}
+              id="channel-public"
+              onCheckedChange={setIsPublic}
+            />
+          </div>
+
+          {error && (
+            <div className="rounded-lg bg-destructive/[0.04] px-3 py-2">
+              <p className="text-[13px] text-destructive/80">{error}</p>
+            </div>
+          )}
+        </div>
+
+        <DialogFooter>
+          <Button
+            className="cursor-pointer"
+            onClick={() => setOpen(false)}
+            variant="outline"
+          >
+            Cancel
+          </Button>
+          <Button
+            className="cursor-pointer"
+            disabled={saving || !name.trim()}
+            onClick={handleCreate}
+          >
+            {saving && <Loader2 className="mr-2 size-4 animate-spin" />}
+            Create Channel
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/page/workspace/channel/room-dnd-toggle.tsx b/src/page/workspace/channel/room-dnd-toggle.tsx
new file mode 100644
index 0000000..291aee8
--- /dev/null
+++ b/src/page/workspace/channel/room-dnd-toggle.tsx
@@ -0,0 +1,146 @@
+import { useCallback, useState } from "react";
+import { Bell, BellOff, MoonStar } from "lucide-react";
+import { api } from "@/client";
+import { Button } from "@/components/ui/button";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Slider } from "@/components/ui/slider";
+import { cn } from "@/lib/utils";
+
+type DndState = {
+  do_not_disturb: boolean;
+  dnd_start_hour?: number;
+  dnd_end_hour?: number;
+};
+
+type Props = {
+  roomId: string;
+};
+
+export default function RoomDndToggle({ roomId }: Props) {
+  const [dnd, setDnd] = useState<DndState>({ do_not_disturb: false });
+  const [loading, setLoading] = useState(false);
+
+  const toggle = useCallback(async () => {
+    setLoading(true);
+    const next = !dnd.do_not_disturb;
+    try {
+      await api.patch(`/api/v1/ws/rooms/${roomId}/dnd`, {
+        do_not_disturb: next,
+        dnd_start_hour: dnd.dnd_start_hour ?? 22,
+        dnd_end_hour: dnd.dnd_end_hour ?? 7,
+      });
+      setDnd((prev) => ({ ...prev, do_not_disturb: next }));
+    } finally {
+      setLoading(false);
+    }
+  }, [dnd.do_not_disturb, dnd.dnd_start_hour, dnd.dnd_end_hour, roomId]);
+
+  const formatHour = (h: number) => {
+    const period = h >= 12 ? "PM" : "AM";
+    const hour = h % 12 || 12;
+    return `${hour} ${period}`;
+  };
+
+  return (
+    <Popover>
+      <PopoverTrigger>
+        <Button
+          className={cn(
+            "size-8 cursor-pointer rounded-lg transition-all duration-150",
+            dnd.do_not_disturb
+              ? "text-amber-500 hover:bg-accent/40"
+              : "text-muted-foreground/40 hover:bg-accent/40 hover:text-muted-foreground",
+          )}
+          size="icon"
+          title={
+            dnd.do_not_disturb ? "Do Not Disturb ON" : "Do Not Disturb OFF"
+          }
+          variant="ghost"
+        >
+          {dnd.do_not_disturb ? (
+            <BellOff className="size-[18px]" />
+          ) : (
+            <Bell className="size-[18px]" />
+          )}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent align="end" className="w-64" side="bottom">
+        <div className="space-y-3">
+          <div className="flex items-center justify-between">
+            <div>
+              <p className="text-sm font-semibold text-foreground">
+                Do Not Disturb
+              </p>
+              <p className="text-[11px] text-muted-foreground/40">
+                {dnd.do_not_disturb
+                  ? "Notifications are muted"
+                  : "Notifications are on"}
+              </p>
+            </div>
+            <Button
+              className="cursor-pointer rounded-lg"
+              disabled={loading}
+              onClick={toggle}
+              size="sm"
+              variant={dnd.do_not_disturb ? "default" : "outline"}
+            >
+              {dnd.do_not_disturb ? "Turn Off" : "Turn On"}
+            </Button>
+          </div>
+
+          {dnd.do_not_disturb && (
+            <div className="space-y-3 rounded-lg bg-muted/20 p-3">
+              <div className="flex items-center gap-2 text-[11px] text-muted-foreground/50">
+                <MoonStar className="size-3.5 text-indigo-400/70" />
+                <span>
+                  Quiet hours: {formatHour(dnd.dnd_start_hour ?? 22)} –{" "}
+                  {formatHour(dnd.dnd_end_hour ?? 7)}
+                </span>
+              </div>
+              <div className="flex gap-3">
+                <div className="flex-1 space-y-1.5">
+                  <label className="text-[10px] font-medium uppercase tracking-wider text-muted-foreground/40">
+                    Start
+                  </label>
+                  <Slider
+                    defaultValue={[dnd.dnd_start_hour ?? 22]}
+                    max={23}
+                    min={0}
+                    onValueChange={(val) =>
+                      setDnd((prev) => ({
+                        ...prev,
+                        dnd_start_hour: Array.isArray(val) ? val[0] : val,
+                      }))
+                    }
+                    step={1}
+                  />
+                </div>
+                <div className="flex-1 space-y-1.5">
+                  <label className="text-[10px] font-medium uppercase tracking-wider text-muted-foreground/40">
+                    End
+                  </label>
+                  <Slider
+                    defaultValue={[dnd.dnd_end_hour ?? 7]}
+                    max={23}
+                    min={0}
+                    onValueChange={(val) =>
+                      setDnd((prev) => ({
+                        ...prev,
+                        dnd_end_hour: Array.isArray(val) ? val[0] : val,
+                      }))
+                    }
+                    step={1}
+                  />
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
diff --git a/src/page/workspace/channel/room-settings-dialog.tsx b/src/page/workspace/channel/room-settings-dialog.tsx
new file mode 100644
index 0000000..457315d
--- /dev/null
+++ b/src/page/workspace/channel/room-settings-dialog.tsx
@@ -0,0 +1,258 @@
+import { useCallback, useEffect, useState } from "react";
+import { Hash, Loader2, Trash2 } from "lucide-react";
+import { api } from "@/client";
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { NativeSelect } from "@/components/ui/native-select";
+import { Switch } from "@/components/ui/switch";
+import { Textarea } from "@/components/ui/textarea";
+import { useToast } from "@/hooks/use-toast";
+import type { Category } from "./channel-sidebar";
+
+type Props = {
+  roomId: string;
+  roomName: string;
+  topic?: string | null;
+  isPrivate: boolean;
+  categoryId?: string | null;
+  categories: Category[];
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onUpdated?: () => void;
+  onDeleted?: () => void;
+};
+
+export default function RoomSettingsDialog({
+  roomId,
+  roomName,
+  topic,
+  isPrivate,
+  categoryId,
+  categories,
+  open,
+  onOpenChange,
+  onUpdated,
+  onDeleted,
+}: Props) {
+  const [name, setName] = useState(roomName);
+  const [topicText, setTopicText] = useState(topic ?? "");
+  const [isPublic, setIsPublic] = useState(!isPrivate);
+  const [category, setCategory] = useState(categoryId ?? "");
+  const [saving, setSaving] = useState(false);
+  const [deleting, setDeleting] = useState(false);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const { toast } = useToast();
+
+  useEffect(() => {
+    setName(roomName);
+    setTopicText(topic ?? "");
+    setIsPublic(!isPrivate);
+    setCategory(categoryId ?? "");
+    setConfirmDelete(false);
+  }, [roomName, topic, isPrivate, categoryId, open]);
+
+  const handleSave = useCallback(async () => {
+    const trimmed = name.trim();
+    if (!trimmed) return;
+    setSaving(true);
+    try {
+      await api.patch(`/api/v1/ws/rooms/${roomId}`, {
+        room_name: trimmed !== roomName ? trimmed : undefined,
+        topic: topicText !== (topic ?? "") ? topicText || null : undefined,
+        public: isPublic !== !isPrivate ? isPublic : undefined,
+        category:
+          (category || null) !== (categoryId ?? null)
+            ? category || null
+            : undefined,
+      });
+      toast({ title: "Room updated" });
+      onUpdated?.();
+      onOpenChange(false);
+    } catch {
+      toast({
+        title: "Error",
+        description: "Failed to update room",
+        variant: "destructive",
+      });
+    } finally {
+      setSaving(false);
+    }
+  }, [
+    name,
+    topicText,
+    isPublic,
+    category,
+    roomId,
+    roomName,
+    topic,
+    isPrivate,
+    categoryId,
+    toast,
+    onUpdated,
+    onOpenChange,
+  ]);
+
+  const handleDelete = useCallback(async () => {
+    if (!confirmDelete) {
+      setConfirmDelete(true);
+      return;
+    }
+    setDeleting(true);
+    try {
+      await api.delete(`/api/v1/ws/rooms/${roomId}`);
+      toast({ title: "Room deleted" });
+      onDeleted?.();
+      onOpenChange(false);
+    } catch {
+      toast({
+        title: "Error",
+        description: "Failed to delete room",
+        variant: "destructive",
+      });
+    } finally {
+      setDeleting(false);
+    }
+  }, [confirmDelete, roomId, toast, onDeleted, onOpenChange]);
+
+  return (
+    <Dialog onOpenChange={onOpenChange} open={open}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2 text-base">
+            <Hash className="size-5 text-primary/60" />
+            Room Settings
+          </DialogTitle>
+          <DialogDescription>Customize #{roomName}</DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <Label className="text-[13px]" htmlFor="rs-name">
+              Name
+            </Label>
+            <Input
+              autoFocus
+              id="rs-name"
+              maxLength={100}
+              onChange={(e) => setName(e.target.value)}
+              value={name}
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label className="text-[13px]" htmlFor="rs-topic">
+              Topic
+            </Label>
+            <Textarea
+              className="resize-none text-sm"
+              id="rs-topic"
+              maxLength={500}
+              onChange={(e) => setTopicText(e.target.value)}
+              placeholder="What's this room about?"
+              rows={2}
+              value={topicText}
+            />
+          </div>
+
+          <div className="space-y-2">
+            <Label className="text-[13px]" htmlFor="rs-category">
+              Category
+            </Label>
+            <NativeSelect
+              id="rs-category"
+              onChange={(e) => setCategory(e.target.value)}
+              value={category}
+            >
+              <option value="">No category</option>
+              {categories.map((cat) => (
+                <option key={cat.id} value={cat.id}>
+                  {cat.name}
+                </option>
+              ))}
+            </NativeSelect>
+          </div>
+
+          <div className="flex items-center justify-between rounded-lg border border-border/30 px-3 py-2.5">
+            <div className="space-y-0.5">
+              <Label className="text-[13px] font-medium" htmlFor="rs-public">
+                Public channel
+              </Label>
+              <p className="text-[11px] text-muted-foreground/40">
+                Anyone in the workspace can join
+              </p>
+            </div>
+            <Switch
+              checked={isPublic}
+              id="rs-public"
+              onCheckedChange={setIsPublic}
+            />
+          </div>
+
+          <div className="rounded-lg border border-destructive/10 bg-destructive/[0.02] p-3">
+            <div className="flex items-center justify-between">
+              <div>
+                <p className="text-sm font-medium text-destructive/80">
+                  Delete channel
+                </p>
+                <p className="text-[11px] text-muted-foreground/40">
+                  This action cannot be undone.
+                </p>
+              </div>
+              {!confirmDelete ? (
+                <Button
+                  className="cursor-pointer"
+                  onClick={handleDelete}
+                  size="sm"
+                  variant="destructive"
+                >
+                  <Trash2 className="mr-1.5 size-3.5" />
+                  Delete
+                </Button>
+              ) : (
+                <Button
+                  className="cursor-pointer"
+                  disabled={deleting}
+                  onClick={handleDelete}
+                  size="sm"
+                  variant="destructive"
+                >
+                  {deleting && (
+                    <Loader2 className="mr-1.5 size-3.5 animate-spin" />
+                  )}
+                  Confirm Delete
+                </Button>
+              )}
+            </div>
+          </div>
+        </div>
+
+        <DialogFooter>
+          <Button
+            className="cursor-pointer"
+            onClick={() => onOpenChange(false)}
+            variant="outline"
+          >
+            Cancel
+          </Button>
+          <Button
+            className="cursor-pointer"
+            disabled={saving || !name.trim()}
+            onClick={handleSave}
+          >
+            {saving && <Loader2 className="mr-2 size-4 animate-spin" />}
+            Save Changes
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/page/workspace/channel/thread-pane.tsx b/src/page/workspace/channel/thread-pane.tsx
new file mode 100644
index 0000000..dca995f
--- /dev/null
+++ b/src/page/workspace/channel/thread-pane.tsx
@@ -0,0 +1,301 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  Loader2,
+  MessageSquarePlus,
+  X,
+  ArrowLeft,
+  Send,
+  Flame,
+  CornerDownRight,
+} from "lucide-react";
+import { api } from "@/client";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import type { MessageNewService } from "@/socket";
+import type { Thread } from "./thread-sidebar";
+
+type Props = {
+  thread: Thread;
+  roomId: string;
+  onClose: () => void;
+};
+
+function formatTime(iso: string) {
+  const d = new Date(iso);
+  return d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+}
+
+function formatDate(iso: string) {
+  const d = new Date(iso);
+  const now = new Date();
+  if (d.toDateString() === now.toDateString()) return "Today";
+  const yesterday = new Date(now);
+  yesterday.setDate(yesterday.getDate() - 1);
+  if (d.toDateString() === yesterday.toDateString()) return "Yesterday";
+  return d.toLocaleDateString([], {
+    month: "long",
+    day: "numeric",
+    year: d.getFullYear() !== now.getFullYear() ? "numeric" : undefined,
+  });
+}
+
+function shouldShowDate(current: string, prev?: string): boolean {
+  if (!prev) return true;
+  const cur = new Date(current);
+  const prv = new Date(prev);
+  return cur.toDateString() !== prv.toDateString();
+}
+
+export default function ThreadPane({ thread, roomId, onClose }: Props) {
+  const [messages, setMessages] = useState<MessageNewService[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [reply, setReply] = useState("");
+  const [sending, setSending] = useState(false);
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  const creatorName =
+    thread.created_by.display_name || thread.created_by.username || "User";
+
+  useEffect(() => {
+    let cancelled = false;
+    api
+      .get<{ data?: { messages?: MessageNewService[] } }>(
+        `/api/v1/ws/rooms/${roomId}/messages/around`,
+        { params: { seq: thread.seq, limit: 30 } },
+      )
+      .then((res) => {
+        if (!cancelled) setMessages(res.data?.data?.messages ?? []);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [thread.seq, roomId]);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages.length]);
+
+  const handleReply = useCallback(async () => {
+    const trimmed = reply.trim();
+    if (!trimmed || sending) return;
+    setSending(true);
+    try {
+      await api.post(`/api/v1/ws/rooms/${roomId}/messages`, {
+        content: trimmed,
+        content_type: "text",
+        thread: thread.id,
+      });
+      setReply("");
+    } catch {
+      // ignore
+    } finally {
+      setSending(false);
+    }
+  }, [reply, sending, roomId, thread.id]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        handleReply();
+      }
+      if (e.key === "Escape") setReply("");
+    },
+    [handleReply],
+  );
+
+  // Group messages by sender
+  const grouped = (() => {
+    const groups: {
+      senderId: string;
+      name: string;
+      avatar_url?: string;
+      colorClass: string;
+      initial: string;
+      messages: { msg: MessageNewService; showHeader: boolean }[];
+    }[] = [];
+
+    let lastDate: string | undefined;
+    for (let i = 0; i < messages.length; i++) {
+      const msg = messages[i];
+      const prev = i > 0 ? messages[i - 1] : undefined;
+      const isFirst =
+        !prev ||
+        prev.sender.id !== msg.sender.id ||
+        new Date(msg.send_at).getTime() -
+          new Date(prev.send_at).getTime() >
+          5 * 60 * 1000;
+
+      const name = msg.sender.display_name || msg.sender.username || "User";
+      const colorClass = workspaceColor(name);
+      const initial = workspaceInitial(name);
+
+      if (isFirst) {
+        groups.push({
+          senderId: msg.sender.id,
+          name,
+          avatar_url: msg.sender.avatar_url,
+          colorClass,
+          initial,
+          messages: [{ msg, showHeader: true }],
+        });
+      } else {
+        groups[groups.length - 1].messages.push({ msg, showHeader: false });
+      }
+    }
+    return groups;
+  })();
+
+  return (
+    <aside className="flex h-full w-full flex-col bg-card">
+      {/* Header */}
+      <div className="flex h-[52px] shrink-0 items-center gap-3 border-b border-border/40 px-4">
+        <Button
+          className="size-7 shrink-0 cursor-pointer rounded-lg text-muted-foreground/40 hover:bg-accent/50 hover:text-foreground"
+          onClick={onClose}
+          size="icon"
+          variant="ghost"
+        >
+          <ArrowLeft className="size-4" />
+        </Button>
+        <div className="min-w-0 flex-1">
+          <h3 className="truncate text-sm font-semibold text-foreground">
+            {thread.title || `Thread #${thread.seq}`}
+          </h3>
+          <div className="flex items-center gap-1.5">
+            <span className="text-[11px] text-muted-foreground/40">
+              {thread.archived
+                ? "Archived"
+                : thread.locked
+                  ? "Resolved"
+                  : "Active"}
+            </span>
+            <span className="text-muted-foreground/20">·</span>
+            <span className="text-[11px] text-muted-foreground/30">
+              {messages.length} message{messages.length !== 1 ? "s" : ""}
+            </span>
+          </div>
+        </div>
+      </div>
+
+      {/* Messages */}
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">
+        {loading && (
+          <div className="flex justify-center py-20">
+            <Loader2 className="size-5 animate-spin text-muted-foreground/25" />
+          </div>
+        )}
+
+        {!loading && messages.length === 0 && (
+          <div className="flex flex-col items-center justify-center py-20">
+            <div className="grid size-12 place-items-center rounded-2xl bg-muted/20 ring-1 ring-border/20">
+              <MessageSquarePlus className="size-5 text-muted-foreground/20" />
+            </div>
+            <p className="mt-3 text-xs font-medium text-muted-foreground/40">
+              No messages yet
+            </p>
+            <p className="mt-1 text-[11px] text-muted-foreground/30">
+              Be the first to reply
+            </p>
+          </div>
+        )}
+
+        <div className="py-2">
+          {grouped.map((group) => (
+            <div
+              className="group flex gap-2.5 px-4 py-1 transition-colors duration-100 hover:bg-accent/[0.02]"
+              key={group.messages[0].msg.id}
+            >
+              <div className="mt-0.5 shrink-0">
+                <div
+                  className={cn(
+                    "grid size-8 place-items-center rounded-full bg-gradient-to-br text-xs font-semibold text-white shadow-sm",
+                    group.colorClass,
+                  )}
+                >
+                  {group.avatar_url ? (
+                    <img
+                      alt={group.name}
+                      className="size-full rounded-full object-cover"
+                      src={group.avatar_url}
+                    />
+                  ) : (
+                    group.initial
+                  )}
+                </div>
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="flex items-baseline gap-2">
+                  <span className="text-[13px] font-semibold text-foreground">
+                    {group.name}
+                  </span>
+                  <span className="text-[10px] text-muted-foreground/35">
+                    {formatTime(group.messages[0].msg.send_at)}
+                  </span>
+                </div>
+                {group.messages.map(({ msg }) => (
+                  <p
+                    className="whitespace-pre-wrap break-words text-[13px] leading-relaxed text-foreground/85"
+                    key={msg.id}
+                  >
+                    {msg.content}
+                  </p>
+                ))}
+              </div>
+            </div>
+          ))}
+          <div ref={bottomRef} />
+        </div>
+      </div>
+
+      {/* Reply composer */}
+      <div className="shrink-0 border-t border-border/40 p-3">
+        <div
+          className={cn(
+            "flex items-end gap-2 rounded-xl border bg-card px-3 py-2 transition-all duration-200",
+            "focus-within:border-primary/20 focus-within:ring-1 focus-within:ring-primary/[0.06]",
+            "border-border/50",
+          )}
+        >
+          <textarea
+            aria-label="Reply in thread"
+            className="min-h-[36px] max-h-32 flex-1 resize-none border-0 bg-transparent text-sm leading-relaxed text-foreground placeholder:text-muted-foreground/30 focus-visible:ring-0 focus-visible:outline-none"
+            disabled={thread.archived || thread.locked}
+            onChange={(e) => setReply(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder={
+              thread.archived || thread.locked
+                ? "Thread is closed"
+                : "Reply in thread…"
+            }
+            ref={textareaRef}
+            rows={1}
+            value={reply}
+          />
+          <Button
+            className="shrink-0 cursor-pointer rounded-lg"
+            disabled={
+              !reply.trim() || sending || thread.archived || thread.locked
+            }
+            onClick={handleReply}
+            size="sm"
+          >
+            {sending ? (
+              <Loader2 className="size-4 animate-spin" />
+            ) : (
+              <Send className="size-[15px]" />
+            )}
+          </Button>
+        </div>
+        <p className="mt-1.5 px-1 text-[10px] text-muted-foreground/25">
+          Press Enter to send, Shift+Enter for new line
+        </p>
+      </div>
+    </aside>
+  );
+}
diff --git a/src/page/workspace/channel/thread-sidebar.tsx b/src/page/workspace/channel/thread-sidebar.tsx
new file mode 100644
index 0000000..225dc97
--- /dev/null
+++ b/src/page/workspace/channel/thread-sidebar.tsx
@@ -0,0 +1,252 @@
+import { useMemo, useState } from "react";
+import {
+  MessageSquare,
+  CheckCircle2,
+  Archive,
+  Lock,
+  X,
+  Flame,
+  ArrowRight,
+  CircleDot,
+} from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
+
+export type Thread = {
+  id: string;
+  room: string;
+  seq: number;
+  title: string;
+  created_by: { id: string; display_name: string; username: string };
+  archived: boolean;
+  locked: boolean;
+  last_message_at: string | null;
+  last_message_preview?: string | null;
+  created_at: string;
+};
+
+type Props = {
+  threads: Thread[];
+  onSelect?: (thread: Thread) => void;
+  onClose?: () => void;
+};
+
+function formatTime(iso: string) {
+  const d = new Date(iso);
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffMin = Math.floor(diffMs / 60000);
+  if (diffMin < 1) return "now";
+  if (diffMin < 60) return `${diffMin}m`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h`;
+  return d.toLocaleDateString([], { month: "short", day: "numeric" });
+}
+
+function ThreadStatusDot({
+  thread,
+}: {
+  thread: Thread;
+}) {
+  if (thread.locked) {
+    return (
+      <span className="flex items-center gap-1 rounded-full bg-primary/[0.05] px-1.5 py-[1px] text-[10px] font-medium text-primary/50">
+        <Lock className="size-2.5" />
+        Resolved
+      </span>
+    );
+  }
+  if (thread.archived) {
+    return (
+      <span className="flex items-center gap-1 rounded-full bg-muted/40 px-1.5 py-[1px] text-[10px] font-medium text-muted-foreground/40">
+        <Archive className="size-2.5" />
+        Archived
+      </span>
+    );
+  }
+  return (
+    <span className="flex items-center gap-1 rounded-full bg-emerald-500/[0.06] px-1.5 py-[1px] text-[10px] font-medium text-emerald-600/70">
+      <CircleDot className="size-2.5" />
+      Active
+    </span>
+  );
+}
+
+export default function ThreadSidebar({
+  threads,
+  onSelect,
+  onClose,
+}: Props) {
+  const [filter, setFilter] = useState<"all" | "active" | "resolved">("all");
+
+  const filtered = threads.filter((t) => {
+    if (filter === "active") return !t.archived && !t.locked;
+    if (filter === "resolved") return t.locked || t.archived;
+    return true;
+  });
+
+  const counts = useMemo(() => {
+    return {
+      all: threads.length,
+      active: threads.filter((t) => !t.archived && !t.locked).length,
+      resolved: threads.filter((t) => t.locked || t.archived).length,
+    };
+  }, [threads]);
+
+  return (
+    <aside className="flex h-full w-full flex-col bg-card">
+      {/* Header */}
+      <div className="flex h-[52px] shrink-0 items-center justify-between border-b border-border/40 px-4">
+        <div className="flex items-center gap-2">
+          <span className="grid size-8 place-items-center rounded-lg bg-gradient-to-br from-primary/10 to-primary/[0.03] ring-1 ring-primary/[0.08]">
+            <MessageSquare className="size-[15px] text-primary/60" />
+          </span>
+          <h3 className="text-[15px] font-semibold text-foreground tracking-tight">
+            Threads
+          </h3>
+          <span className="text-[11px] font-medium text-muted-foreground/30 tabular-nums">
+            {threads.length}
+          </span>
+        </div>
+        {onClose && (
+          <Button
+            className="size-7 cursor-pointer rounded-lg text-muted-foreground/30 hover:bg-accent/50 hover:text-foreground"
+            onClick={onClose}
+            size="icon"
+            variant="ghost"
+          >
+            <X className="size-4" />
+          </Button>
+        )}
+      </div>
+
+      {/* Filter tabs with counts */}
+      <div className="flex gap-0.5 border-b border-border/30 px-3 py-2">
+        {([
+          { key: "all", label: "All" },
+          { key: "active", label: "Active" },
+          { key: "resolved", label: "Resolved" },
+        ] as const).map((f) => {
+          const isActive = filter === f.key;
+          const count =
+            f.key === "all"
+              ? counts.all
+              : f.key === "active"
+                ? counts.active
+                : counts.resolved;
+          return (
+            <button
+              className={cn(
+                "relative flex-1 cursor-pointer rounded-md px-2 py-1.5 text-[11px] font-medium transition-all duration-150",
+                isActive
+                  ? "text-primary"
+                  : "text-muted-foreground/40 hover:text-muted-foreground/70",
+              )}
+              key={f.key}
+              onClick={() => setFilter(f.key)}
+              type="button"
+            >
+              <span className="flex items-center justify-center gap-1.5">
+                {f.label}
+                <span
+                  className={cn(
+                    "text-[10px] tabular-nums transition-colors",
+                    isActive
+                      ? "text-primary/50"
+                      : "text-muted-foreground/20",
+                  )}
+                >
+                  {count}
+                </span>
+              </span>
+              {isActive && (
+                <span className="absolute inset-x-2 -bottom-[2px] h-[2px] rounded-full bg-primary/60" />
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      {/* Thread list */}
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">
+        {filtered.length === 0 && (
+          <div className="flex flex-col items-center justify-center py-20">
+            <div className="grid size-12 place-items-center rounded-2xl bg-muted/20 ring-1 ring-border/20">
+              <MessageSquare className="size-5 text-muted-foreground/20" />
+            </div>
+            <p className="mt-3 text-sm font-medium text-muted-foreground/40">
+              No threads yet
+            </p>
+            <p className="mt-1 text-[11px] text-muted-foreground/30">
+              Start a thread from any message
+            </p>
+          </div>
+        )}
+        {filtered.map((thread, idx) => {
+          const creatorName =
+            thread.created_by.display_name || thread.created_by.username;
+          const initials = creatorName
+            .split(" ")
+            .map((w) => w[0])
+            .join("")
+            .slice(0, 2)
+            .toUpperCase();
+
+          return (
+            <button
+              className="group flex w-full cursor-pointer gap-3 border-b border-border/[0.06] px-4 py-3 text-left transition-all duration-150 hover:bg-accent/[0.03] active:bg-accent/[0.06]"
+              key={thread.id}
+              onClick={() => onSelect?.(thread)}
+              type="button"
+            >
+              {/* Avatar */}
+              <div className="mt-0.5 shrink-0">
+                <div className="grid size-9 place-items-center rounded-full bg-gradient-to-br from-muted-foreground/10 to-muted-foreground/5 text-xs font-semibold text-muted-foreground/50">
+                  {initials}
+                </div>
+              </div>
+
+              {/* Content */}
+              <div className="min-w-0 flex-1">
+                {/* Title + status */}
+                <div className="flex items-center gap-2">
+                  <span className="min-w-0 flex-1 truncate text-[13px] font-semibold text-foreground">
+                    {thread.title || `Thread #${thread.seq}`}
+                  </span>
+                  <ThreadStatusDot thread={thread} />
+                </div>
+
+                {/* Author + time */}
+                <div className="mt-0.5 flex items-center gap-1.5">
+                  <span className="text-[11px] text-muted-foreground/40">
+                    {creatorName}
+                  </span>
+                  <span className="text-[10px] text-muted-foreground/20">
+                    ·
+                  </span>
+                  <span className="text-[11px] text-muted-foreground/30">
+                    {thread.last_message_at
+                      ? formatTime(thread.last_message_at)
+                      : formatTime(thread.created_at)}
+                  </span>
+                </div>
+
+                {/* Preview */}
+                {thread.last_message_preview && (
+                  <p className="mt-1 line-clamp-2 text-[12px] leading-relaxed text-muted-foreground/35 group-hover:text-muted-foreground/50 transition-colors">
+                    {thread.last_message_preview}
+                  </p>
+                )}
+              </div>
+
+              {/* Arrow on hover */}
+              <div className="flex shrink-0 items-center self-center opacity-0 transition-opacity duration-150 group-hover:opacity-100">
+                <ArrowRight className="size-4 text-muted-foreground/30" />
+              </div>
+            </button>
+          );
+        })}
+      </div>
+    </aside>
+  );
+}
diff --git a/src/page/workspace/channel/use-channel-state.ts b/src/page/workspace/channel/use-channel-state.ts
new file mode 100644
index 0000000..b386519
--- /dev/null
+++ b/src/page/workspace/channel/use-channel-state.ts
@@ -0,0 +1,708 @@
+import {useCallback, useEffect, useMemo, useRef, useState} from "react";
+import {useQuery, useQueryClient} from "@tanstack/react-query";
+
+import {api} from "@/client";
+import {useAuth} from "@/context/auth-context";
+import {useChannelSocket, type WsOutEvent} from "@/hooks/use-channel";
+import {useMessageCache} from "@/hooks/use-message-cache";
+import {useToast} from "@/hooks/use-toast";
+import type {
+  MessageEditedService,
+  MessageNewService,
+  MessageRevokedService,
+  MessageStreamChunkService,
+  MessageStreamDoneService,
+  MessageStreamStartService,
+  PinAddedService,
+  PinRemovedService,
+  ReactionAddedService,
+  ReactionBatchUpdatedService,
+  ReactionRemovedService,
+  RoomDeletedService,
+  RoomRenamedService,
+  RoomTopicUpdatedService,
+  ThreadArchivedService,
+  ThreadCreatedService,
+  ThreadResolvedService,
+  ThreadUpdatedService,
+} from "@/socket";
+import type {Category, Room} from "./channel-sidebar";
+import type {Thread} from "./thread-sidebar";
+
+type TypingUser = {
+  userId: string;
+  displayName: string;
+};
+
+export type ChannelState = {
+  messages: MessageNewService[];
+  loadingMessages: boolean;
+  hasMore: boolean;
+  typingUsers: TypingUser[];
+  typingText: string | null;
+  threads: Thread[];
+  streamingMessages: Map<string, { content: string; displayName?: string }>;
+  rooms: Room[];
+  categories: Category[];
+  currentRoom: Room | undefined;
+  loadingRooms: boolean;
+  currentUserId?: string;
+};
+
+export type ChannelActions = {
+  handleSend: (content: string, inReplyTo?: string) => Promise<void>;
+  handleLoadMore: () => void;
+  handleTyping: (typing: boolean) => void;
+  handlePinToggle: (messageId: string, pinned: boolean) => void;
+  handleDeleteMessage: (messageId: string) => void;
+  handleEditMessage: (messageId: string, content: string) => void;
+  handleStartThread: (messageId: string, seq: number) => void;
+  handleReactionToggle: (messageId: string, emoji: string, add: boolean) => void;
+};
+
+export function useChannelState(roomId: string | undefined) {
+  const { subscribe, unsubscribe, send, onEvent } = useChannelSocket();
+  const { user } = useAuth();
+  const currentUserId = user?.id;
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+  const messageCache = useMessageCache(roomId ?? undefined);
+
+  const [messages, setMessages] = useState<MessageNewService[]>([]);
+  const [loadingMessages, setLoadingMessages] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+  const [typingUsers, setTypingUsers] = useState<TypingUser[]>([]);
+  const [threads, setThreads] = useState<Thread[]>([]);
+  const [streamingMessages, setStreamingMessages] = useState<
+    Map<string, { content: string; displayName?: string }>
+  >(new Map());
+
+  const lastSeq = useRef(0);
+  const prevRoomId = useRef<string | undefined>(undefined);
+
+  const { data: channelData, isLoading: loadingRooms } = useQuery({
+    queryKey: ["channel", "rooms"],
+    queryFn: async () => {
+      const response = await api.get<{ rooms: Room[]; categories: Category[] }>(
+        "/api/v1/ws/rooms",
+      );
+      return response.data;
+    },
+    retry: false,
+  });
+  const rooms = channelData?.rooms ?? [];
+  const categories = channelData?.categories ?? [];
+
+  const currentRoom = useMemo(
+    () => rooms.find((r) => r.id === roomId),
+    [rooms, roomId],
+  );
+
+  const loadMessages = useCallback(
+    async (targetRoomId: string, beforeSeq?: number) => {
+      if (!targetRoomId) return;
+      setLoadingMessages(true);
+      try {
+        const params: Record<string, string | number> = { limit: 50 };
+        if (beforeSeq) params.before_seq = beforeSeq;
+
+        const response = await api.get<WsOutEvent>(
+          `/api/v1/ws/rooms/${targetRoomId}/messages`,
+          { params },
+        );
+
+        const result = (response.data as Record<string, unknown>)?.data as { messages?: MessageNewService[] } | undefined;
+        if (result?.messages) {
+          const msgs = result.messages as MessageNewService[];
+          messageCache.persistBatch(msgs).catch(() => {});
+          if (beforeSeq) {
+            setMessages((prev) => [...msgs, ...prev]);
+            setHasMore(msgs.length >= 50);
+          } else {
+            setMessages(msgs);
+            setHasMore(msgs.length >= 50);
+            if (msgs.length > 0) {
+              lastSeq.current = msgs[msgs.length - 1].seq;
+            }
+          }
+        }
+      } catch (err) {
+        console.error("Failed to load messages:", err);
+      } finally {
+        setLoadingMessages(false);
+      }
+    },
+    [messageCache],
+  );
+
+  useEffect(() => {
+    if (!roomId) return;
+
+    if (prevRoomId.current && prevRoomId.current !== roomId) {
+      unsubscribe(prevRoomId.current);
+      setMessages([]);
+      setHasMore(true);
+      setTypingUsers([]);
+      setStreamingMessages(new Map());
+      setThreads([]);
+      lastSeq.current = 0;
+    }
+
+    prevRoomId.current = roomId;
+    subscribe(roomId);
+    loadMessages(roomId);
+
+    return () => {
+      unsubscribe(roomId);
+    };
+  }, [roomId, subscribe, unsubscribe, loadMessages]);
+
+  useEffect(() => {
+    return onEvent((event: WsOutEvent) => {
+      if (!roomId) return;
+
+      switch (event.type) {
+        case "message_new": {
+          if (event.room.id !== roomId) break;
+          const msg = event.data as MessageNewService;
+          messageCache.persistMessage(msg).catch(() => {
+          });
+          setMessages((prev) => {
+            if (prev.some((m) => m.id === msg.id)) return prev;
+            return [...prev, msg];
+          });
+          if (msg.seq > lastSeq.current) lastSeq.current = msg.seq;
+          break;
+        }
+        case "message_edited": {
+          if (event.room.id !== roomId) break;
+          const edited = event.data as MessageEditedService;
+          setMessages((prev) =>
+              prev.map((m) =>
+                  m.id === edited.id ? {...m, content: edited.content} : m,
+              ),
+          );
+          break;
+        }
+        case "message_revoked": {
+          if (event.room.id !== roomId) break;
+          const revoked = event.data as MessageRevokedService;
+          setMessages((prev) => prev.filter((m) => m.id !== revoked.id));
+          break;
+        }
+
+        case "message_stream_start": {
+          if (event.room.id !== roomId) break;
+          const data = event.data as MessageStreamStartService;
+          setStreamingMessages((prev) =>
+              new Map(prev).set(data.message_id, {
+                content: "",
+                displayName: data.display_name ?? undefined,
+              }),
+          );
+          break;
+        }
+        case "message_stream_chunk": {
+          if (event.room.id !== roomId) break;
+          const data = event.data as MessageStreamChunkService;
+          setStreamingMessages((prev) => {
+            const next = new Map(prev);
+            const existing = next.get(data.message_id);
+            next.set(data.message_id, {
+              content: (existing?.content ?? "") + data.content,
+              displayName:
+                  existing?.displayName ?? data.display_name ?? undefined,
+            });
+            return next;
+          });
+          break;
+        }
+        case "message_stream_done": {
+          if (event.room.id !== roomId) break;
+          const data = event.data as MessageStreamDoneService;
+          setStreamingMessages((prev) => {
+            const next = new Map(prev);
+            next.delete(data.message_id);
+            return next;
+          });
+          if (data.error) {
+            toast({
+              title: "AI Error",
+              description: data.error,
+              variant: "destructive",
+            });
+          }
+          break;
+        }
+
+        case "reaction_batch_updated": {
+          if (event.room.id !== roomId) break;
+          const batch = event.data as ReactionBatchUpdatedService;
+          setMessages((prev) =>
+              prev.map((m) =>
+                  m.id === batch.message
+                      ? {...m, reactions: batch.reactions}
+                      : m,
+              ),
+          );
+          break;
+        }
+        case "reaction_added": {
+          if (event.room.id !== roomId) break;
+          const r = event.data as ReactionAddedService;
+          const reactedByMe = r.user.id === currentUserId;
+          setMessages((prev) =>
+              prev.map((m) => {
+                if (m.id !== r.message) return m;
+                const existing = m.reactions?.find((g) => g.emoji === r.emoji);
+                if (existing) {
+                  if (reactedByMe && existing.users.some((u) => u.id === currentUserId)) {
+                    return m;
+                  }
+                  return {
+                    ...m,
+                    reactions: m.reactions.map((g) =>
+                        g.emoji === r.emoji
+                            ? {
+                              ...g,
+                              count: g.count + 1,
+                              reacted_by_me: g.reacted_by_me || reactedByMe,
+                              users: g.users.some((u) => u.id === r.user.id)
+                                  ? g.users
+                                  : [...g.users, r.user],
+                            }
+                            : g,
+                    ),
+                  };
+                }
+                return {
+                  ...m,
+                  reactions: [
+                    ...(m.reactions ?? []),
+                    {
+                      emoji: r.emoji,
+                      count: 1,
+                      reacted_by_me: reactedByMe,
+                      users: [r.user],
+                    },
+                  ],
+                };
+              }),
+          );
+          break;
+        }
+        case "reaction_removed": {
+          if (event.room.id !== roomId) break;
+          const r = event.data as ReactionRemovedService;
+          const removedByMe = r.user.id === currentUserId;
+          setMessages((prev) =>
+              prev.map((m) => {
+                if (m.id !== r.message) return m;
+                if (removedByMe) {
+                  const group = m.reactions?.find((g) => g.emoji === r.emoji);
+                  if (group && !group.users.some((u) => u.id === currentUserId)) {
+                    return m;
+                  }
+                }
+                return {
+                  ...m,
+                  reactions: (m.reactions ?? []).flatMap((g) => {
+                    if (g.emoji !== r.emoji) return [g];
+                    const count = Math.max(0, g.count - 1);
+                    return count > 0
+                      ? [{ ...g, count, reacted_by_me: removedByMe ? false : g.reacted_by_me, users: g.users.filter((u) => u.id !== r.user.id) }]
+                      : [];
+                  }),
+                };
+              }),
+          );
+          break;
+        }
+
+        case "typing_start": {
+          if (event.room.id !== roomId) break;
+          const t = event.data as { user: { id: string; display_name?: string; username?: string } };
+          const uid = t.user.id;
+          if (!uid) break;
+          setTypingUsers((prev) => {
+            if (prev.some((u) => u.userId === uid)) return prev;
+            return [
+              ...prev,
+              {
+                userId: uid,
+                displayName:
+                    t.user.display_name || t.user.username || "Someone",
+              },
+            ];
+          });
+          break;
+        }
+        case "typing_stop": {
+          if (event.room.id !== roomId) break;
+          const sd = event.data as { user: { id: string } };
+          const uid = sd.user.id;
+          if (!uid) break;
+          setTypingUsers((prev) => prev.filter((x) => x.userId !== uid));
+          break;
+        }
+
+        case "pin_added": {
+          if (event.room.id !== roomId) break;
+          const pin = event.data as PinAddedService;
+          setMessages((prev) =>
+              prev.map((m) => (m.id === pin.message ? {...m, pinned: true} : m)),
+          );
+          break;
+        }
+        case "pin_removed": {
+          if (event.room.id !== roomId) break;
+          const pinR = event.data as PinRemovedService;
+          setMessages((prev) =>
+              prev.map((m) => (m.id === pinR.message ? {...m, pinned: false} : m)),
+          );
+          break;
+        }
+
+        case "thread_created": {
+          if (event.room.id !== roomId) break;
+          const tc = event.data as ThreadCreatedService;
+          setThreads((prev) => {
+            if (prev.some((t) => t.id === tc.id)) return prev;
+            return [
+              ...prev,
+              {
+                id: tc.id,
+                room: tc.room.id,
+                seq: tc.parent,
+                title: "",
+                created_by: tc.created_by,
+                archived: false,
+                locked: false,
+                last_message_at: null,
+                created_at: tc.created_at,
+              },
+            ];
+          });
+          toast({
+            title: "Thread created",
+            description: `${tc.created_by.display_name || "Someone"} started a thread`,
+          });
+          break;
+        }
+        case "thread_updated": {
+          if (event.room.id !== roomId) break;
+          const tu = event.data as ThreadUpdatedService;
+          setThreads((prev) =>
+              prev.map((t) =>
+                  t.id === tu.id
+                      ? {
+                        ...t,
+                        last_message_at: tu.last_message_at,
+                        last_message_preview: tu.last_message_preview,
+                      }
+                      : t,
+              ),
+          );
+          break;
+        }
+        case "thread_resolved": {
+          if (event.room.id !== roomId) break;
+          const tr = event.data as ThreadResolvedService;
+          setThreads((prev) =>
+              prev.map((t) => (t.id === tr.id ? {...t, locked: true} : t)),
+          );
+          break;
+        }
+        case "thread_archived": {
+          if (event.room.id !== roomId) break;
+          const ta = event.data as ThreadArchivedService;
+          setThreads((prev) =>
+              prev.map((t) => (t.id === ta.id ? {...t, archived: true} : t)),
+          );
+          break;
+        }
+
+        case "room_deleted": {
+          const d = event.data as RoomDeletedService;
+          if (d.room.id === roomId) {
+            toast({title: "Room deleted", description: `#${d.room.name} was deleted`});
+          }
+          queryClient.invalidateQueries({queryKey: ["channel", "rooms"]});
+          break;
+        }
+        case "room_renamed": {
+          const d = event.data as RoomRenamedService;
+          toast({title: "Room renamed", description: `#${d.old_name} → #${d.new_name}`});
+          queryClient.invalidateQueries({queryKey: ["channel", "rooms"]});
+          break;
+        }
+        case "room_topic_updated": {
+          const d = event.data as RoomTopicUpdatedService;
+          queryClient.setQueryData<{ rooms: Room[]; categories: Category[] }>(
+              ["channel", "rooms"],
+              (old) => {
+                if (!old) return old;
+                return {
+                  ...old,
+                  rooms: old.rooms.map((r) =>
+                      r.id === d.room.id ? {...r, topic: d.new_topic} : r,
+                  ),
+                };
+              },
+          );
+          break;
+        }
+
+        case "room_created":
+        case "room_moved":
+        case "category_created":
+        case "category_updated":
+        case "category_deleted":
+        case "workspace_room_created":
+        case "workspace_room_deleted":
+          queryClient.invalidateQueries({queryKey: ["channel", "rooms"]});
+          break;
+
+        case "room_settings_updated":
+          toast({title: "Room settings updated"});
+          break;
+
+        case "user_banned": {
+          const b = event.data as { user: { username?: string } };
+          toast({title: "User banned", description: `${b.user.username || "User"} was banned`});
+          queryClient.invalidateQueries({queryKey: ["channel", "rooms"]});
+          break;
+        }
+        case "user_unbanned": {
+          const ub = event.data as { user: { username?: string } };
+          toast({title: "User unbanned", description: `${ub.user.username || "User"} was unbanned`});
+          break;
+        }
+
+        case "invite_created": {
+          const ic = event.data as { code: string };
+          toast({title: "Invite created", description: `Invite code: ${ic.code}`});
+          break;
+        }
+        case "invite_accepted": {
+          const ia = event.data as { user: { username?: string } };
+          toast({title: "Invite accepted", description: `${ia.user.username || "Someone"} joined`});
+          queryClient.invalidateQueries({queryKey: ["channel", "rooms"]});
+          break;
+        }
+
+        case "notify_created": {
+          const nc = event.data as { title: string; content?: string | null };
+          toast({title: nc.title, description: nc.content ?? undefined});
+          break;
+        }
+
+        case "voice_channel_joined": {
+          const vj = event.data as { user: { display_name?: string } };
+          toast({title: "Voice", description: `${vj.user.display_name || "Someone"} joined voice`});
+          break;
+        }
+
+        case "attachment_uploaded": {
+          const au = event.data as { filename: string };
+          toast({title: "File uploaded", description: au.filename});
+          break;
+        }
+      }
+    });
+  }, [roomId, currentUserId, onEvent, queryClient, toast, messageCache]);
+
+  const handleSend = useCallback(
+    async (content: string, inReplyTo?: string) => {
+      if (!roomId) return;
+      try {
+        const body: Record<string, unknown> = { content, content_type: "text" };
+        if (inReplyTo) body.in_reply_to = inReplyTo;
+        const res = await api.post<{ data?: MessageNewService }>(
+          `/api/v1/ws/rooms/${roomId}/messages`,
+          body,
+        );
+        const msg = res.data?.data;
+        if (msg) {
+          messageCache.persistMessage(msg).catch(() => {});
+          setMessages((prev) => {
+            if (prev.some((m) => m.id === msg.id)) return prev;
+            return [...prev, msg];
+          });
+          if (msg.seq > lastSeq.current) lastSeq.current = msg.seq;
+        }
+      } catch (err) {
+        console.error("Failed to send message:", err);
+        toast({
+          title: "Error",
+          description: "Failed to send message",
+          variant: "destructive",
+        });
+      }
+    },
+    [roomId, messageCache, toast],
+  );
+
+  const handleLoadMore = useCallback(() => {
+    if (!roomId || messages.length === 0) return;
+    loadMessages(roomId, messages[0].seq);
+  }, [roomId, messages, loadMessages]);
+
+  const handleTyping = useCallback(
+    (typing: boolean) => {
+      if (!roomId) return;
+      send({
+        type: typing ? "typing_start" : "typing_stop",
+        room: roomId,
+      }).catch(() => {});
+    },
+    [roomId, send],
+  );
+
+  const handlePinToggle = useCallback(
+    async (messageId: string, pinned: boolean) => {
+      if (!roomId) return;
+      if (pinned) {
+        await api.post(`/api/v1/ws/rooms/${roomId}/pins`, { message: messageId });
+      } else {
+        await api.delete(`/api/v1/ws/rooms/${roomId}/pins`, {
+          data: { message: messageId },
+        });
+      }
+    },
+    [roomId],
+  );
+
+  const handleDeleteMessage = useCallback(
+    async (messageId: string) => {
+      try {
+        await api.delete(`/api/v1/ws/messages/${messageId}`);
+      } catch (err) {
+        console.error("Failed to delete message:", err);
+        toast({
+          title: "Error",
+          description: "Failed to delete message",
+          variant: "destructive",
+        });
+      }
+    },
+    [toast],
+  );
+
+  const handleEditMessage = useCallback(
+    async (messageId: string, content: string) => {
+      try {
+        await api.patch(`/api/v1/ws/messages/${messageId}`, { content });
+      } catch (err) {
+        console.error("Failed to edit message:", err);
+        toast({
+          title: "Error",
+          description: "Failed to edit message",
+          variant: "destructive",
+        });
+      }
+    },
+    [toast],
+  );
+
+  const handleStartThread = useCallback(
+    async (_messageId: string, seq: number) => {
+      if (!roomId) return;
+      await api.post(`/api/v1/ws/rooms/${roomId}/threads`, { parent: seq });
+    },
+    [roomId],
+  );
+
+  const handleReactionToggle = useCallback(
+    (messageId: string, emoji: string, add: boolean) => {
+      setMessages((prev) =>
+        prev.map((m) => {
+          if (m.id !== messageId) return m;
+
+          if (add) {
+            const existing = m.reactions?.find((g) => g.emoji === emoji);
+            if (existing && existing.users.some((u) => u.id === currentUserId)) {
+              return m;
+            }
+            const me = {
+              id: currentUserId ?? "",
+              username: user?.username ?? "",
+              display_name: user?.display_name ?? "",
+              avatar_url: user?.avatar_url ?? "",
+            };
+            if (existing) {
+              return {
+                ...m,
+                reactions: m.reactions!.map((g) =>
+                  g.emoji === emoji
+                    ? {
+                        ...g,
+                        count: g.count + 1,
+                        reacted_by_me: true,
+                        users: [...g.users, me],
+                      }
+                    : g,
+                ),
+              };
+            }
+            return {
+              ...m,
+              reactions: [
+                ...(m.reactions ?? []),
+                { emoji, count: 1, reacted_by_me: true, users: [me] },
+              ],
+            };
+          } else {
+            return {
+              ...m,
+              reactions: (m.reactions ?? []).flatMap((g) => {
+                if (g.emoji !== emoji) return [g];
+                const count = Math.max(0, g.count - 1);
+                return count > 0
+                  ? [{ ...g, count, reacted_by_me: false, users: g.users.filter((u) => u.id !== currentUserId) }]
+                  : [];
+              }),
+            };
+          }
+        }),
+      );
+    },
+    [currentUserId, user],
+  );
+
+  const typingText = useMemo(() => {
+    if (typingUsers.length === 0) return null;
+    if (typingUsers.length === 1)
+      return `${typingUsers[0].displayName} is typing...`;
+    if (typingUsers.length === 2)
+      return `${typingUsers[0].displayName} and ${typingUsers[1].displayName} are typing...`;
+    return `${typingUsers[0].displayName} and ${typingUsers.length - 1} others are typing...`;
+  }, [typingUsers]);
+
+  return {
+    state: {
+      messages,
+      loadingMessages,
+      hasMore,
+      typingUsers,
+      typingText,
+      threads,
+      streamingMessages,
+      rooms,
+      categories,
+      currentRoom,
+      loadingRooms,
+      currentUserId,
+    } satisfies ChannelState,
+    actions: {
+      handleSend,
+      handleLoadMore,
+      handleTyping,
+      handlePinToggle,
+      handleDeleteMessage,
+      handleEditMessage,
+      handleStartThread,
+      handleReactionToggle,
+    } satisfies ChannelActions,
+  };
+}
diff --git a/src/page/workspace/create.tsx b/src/page/workspace/create.tsx
new file mode 100644
index 0000000..49231e8
--- /dev/null
+++ b/src/page/workspace/create.tsx
@@ -0,0 +1,131 @@
+import { useState, type FormEvent } from "react";
+import { useNavigate } from "react-router";
+import { useQueryClient } from "@tanstack/react-query";
+import { Loader2 } from "lucide-react";
+
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+
+export function CreateWorkspaceDialog({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const [open, setOpen] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+    const name = form.get("name") as string;
+    const description = (form.get("description") as string) || null;
+
+    if (!name.trim()) {
+      setError("Workspace name is required.");
+      setSubmitting(false);
+      return;
+    }
+
+    try {
+      await client.workspaceCreateWorkspace({
+        name: name.trim(),
+        description,
+      });
+      await queryClient.invalidateQueries({ queryKey: ["workspace", "my"] });
+      setOpen(false);
+      navigate(`/${name.trim()}/repos`);
+    } catch (requestError) {
+      setError(
+        requestError instanceof Error
+          ? requestError.message
+          : "Failed to create workspace. Please try again."
+      );
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger render={children as React.ReactElement} />
+      <DialogContent className="sm:max-w-md p-6">
+        <DialogHeader>
+          <DialogTitle className="text-lg font-semibold text-zinc-950">
+            Create a new workspace
+          </DialogTitle>
+          <DialogDescription className="text-base text-zinc-500">
+            Workspaces organize your projects, repositories, and team collaboration.
+          </DialogDescription>
+        </DialogHeader>
+
+        <form
+          className="mt-6 space-y-5"
+          onSubmit={(event) => void handleSubmit(event)}
+        >
+          <div className="space-y-2">
+            <Label className="text-sm font-semibold text-zinc-950" htmlFor="wk-name">
+              Name
+            </Label>
+            <Input
+              className="h-12 rounded-xl border-zinc-300 bg-zinc-50 text-base"
+              id="wk-name"
+              name="name"
+              placeholder="e.g. my-project"
+              required
+              autoFocus
+            />
+            <p className="text-sm text-zinc-400">
+              This will be used as your workspace URL. Use lowercase letters, numbers, and hyphens.
+            </p>
+          </div>
+
+          <div className="space-y-2">
+            <Label className="text-sm font-semibold text-zinc-950" htmlFor="wk-description">
+              Description
+            </Label>
+            <Textarea
+              className="min-h-24 rounded-xl border-zinc-300 bg-zinc-50 text-base"
+              id="wk-description"
+              name="description"
+              placeholder="What is this workspace about?"
+            />
+          </div>
+
+          {error && (
+            <p className="rounded-xl bg-red-50 px-4 py-3 text-sm font-medium text-red-600">
+              {error}
+            </p>
+          )}
+
+          <DialogFooter className="-mx-6 -mb-6 rounded-b-xl border-t border-zinc-200 bg-zinc-50 px-6 py-4 sm:flex-row sm:justify-end">
+            <Button
+              className="h-11 rounded-xl bg-zinc-950 px-5 text-base text-white shadow-inner shadow-white/10 hover:bg-zinc-800"
+              disabled={submitting}
+              type="submit"
+            >
+              {submitting ? <Loader2 className="size-5 animate-spin" /> : "Create workspace"}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/issues/comment-section.tsx b/src/page/workspace/issues/comment-section.tsx
new file mode 100644
index 0000000..41a943c
--- /dev/null
+++ b/src/page/workspace/issues/comment-section.tsx
@@ -0,0 +1,333 @@
+import { useState, type FormEvent } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type IssueCommentResponse, type IssueAuthor } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@/components/ui/alert-dialog";
+import { cn } from "@/lib/utils";
+import { useToast } from "@/hooks/use-toast";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import {
+  MessageSquare,
+  Pencil,
+  Trash2,
+  Smile,
+} from "lucide-react";
+
+const REACTION_EMOJIS = ["👍", "👎", "😄", "🎉", "😕", "❤️", "🚀", "👀"];
+
+function formatRelative(date: string) {
+  const now = Date.now();
+  const diff = now - new Date(date).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.floor(hrs / 24);
+  if (days < 30) return `${days}d ago`;
+  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
+  return `${Math.floor(days / 365)}y ago`;
+}
+
+function AuthorAvatar({ author }: { author: IssueAuthor }) {
+  const name = author.display_name ?? author.username;
+  return (
+    <span
+      className={cn(
+        "grid size-5 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {author.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={author.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+function CommentReactions({
+  comment,
+  projectName,
+  issueNumber,
+  queryKey,
+}: {
+  comment: IssueCommentResponse & { reactions?: Array<{ id: string; reaction: string; user: IssueAuthor; created_at: string }> };
+  projectName: string;
+  issueNumber: number;
+  queryKey: unknown[];
+}) {
+  const qc = useQueryClient();
+  const [open, setOpen] = useState(false);
+  const { toast } = useToast();
+
+  const reactions = (comment as any).reactions ?? [];
+
+  const addReaction = useMutation({
+    mutationFn: async (reaction: string) => {
+      await client.issuesAddCommentReaction(projectName, issueNumber, String(comment.id), { reaction });
+    },
+    onSuccess: () => { qc.invalidateQueries({ queryKey }); setOpen(false); },
+    onError: (e: any) => toast({ title: "Failed to add reaction", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const removeReaction = useMutation({
+    mutationFn: async (reaction: string) => {
+      await client.issuesRemoveCommentReaction(projectName, issueNumber, String(comment.id), { data: { reaction } } as any);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed to remove reaction", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  // Group reactions by emoji
+  const grouped = new Map<string, string[]>();
+  for (const r of reactions) {
+    if (!grouped.has(r.reaction)) grouped.set(r.reaction, []);
+    grouped.get(r.reaction)!.push(r.id);
+  }
+
+  return (
+    <div className="flex items-center gap-1.5 mt-1.5">
+      {[...grouped.entries()].map(([emoji, ids]) => (
+        <button
+          key={emoji}
+          className="inline-flex items-center gap-0.5 rounded-full border border-border bg-muted/50 px-1.5 py-0.5 text-[11px] leading-none hover:bg-muted transition-colors cursor-pointer"
+          onClick={() => removeReaction.mutate(emoji)}
+        >
+          {emoji} <span className="font-mono text-[10px] text-muted-foreground">{ids.length}</span>
+        </button>
+      ))}
+      <button
+        className="inline-flex items-center rounded-full border border-transparent px-1 py-0.5 text-[11px] text-muted-foreground hover:border-border hover:bg-muted/50 transition-colors cursor-pointer"
+        onClick={() => setOpen(!open)}
+      >
+        <Smile className="size-3" />
+      </button>
+      {open && (
+        <div className="absolute z-10 mt-6 flex items-center gap-1 rounded-md border border-border bg-popover p-1 shadow-md">
+          {REACTION_EMOJIS.map((emoji) => (
+            <button
+              key={emoji}
+              className="grid size-6 place-items-center rounded text-[13px] hover:bg-muted cursor-pointer"
+              onClick={() => addReaction.mutate(emoji)}
+            >
+              {emoji}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function CommentItem({
+  comment,
+  projectName,
+  issueNumber,
+  queryKey,
+  currentUsername,
+}: {
+  comment: IssueCommentResponse & { reactions?: Array<{ id: string; reaction: string; user: IssueAuthor; created_at: string }> };
+  projectName: string;
+  issueNumber: number;
+  queryKey: unknown[];
+  currentUsername?: string;
+}) {
+  const [editing, setEditing] = useState(false);
+  const [editBody, setEditBody] = useState(comment.body);
+  const [saving, setSaving] = useState(false);
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const isOwn = currentUsername ? comment.author.username === currentUsername : false;
+
+  const updateMutation = useMutation({
+    mutationFn: async () => {
+      await client.issuesUpdateComment(projectName, issueNumber, String(comment.id), { body: editBody });
+    },
+    onSuccess: () => { qc.invalidateQueries({ queryKey }); setEditing(false); },
+    onError: (e: any) => toast({ title: "Failed to update comment", description: String(e?.message ?? e), variant: "destructive" }),
+    onSettled: () => setSaving(false),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: async () => {
+      await client.issuesDeleteComment(projectName, issueNumber, String(comment.id));
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed to delete comment", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  return (
+    <div className="group border-b border-border py-3 last:border-b-0">
+      <div className="flex items-center gap-2">
+        <AuthorAvatar author={comment.author} />
+        <span className="font-heading text-[13px] font-medium text-foreground">
+          {comment.author.display_name ?? comment.author.username}
+        </span>
+        <span className="font-mono text-[11px] text-muted-foreground">
+          {formatRelative(comment.created_at)}
+        </span>
+        {isOwn && (
+          <div className="ml-auto flex items-center gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
+            <button
+              className="grid size-6 place-items-center rounded text-muted-foreground hover:text-foreground hover:bg-muted cursor-pointer"
+              onClick={() => { setEditing(true); setEditBody(comment.body); }}
+            >
+              <Pencil className="size-3" />
+            </button>
+            <AlertDialog>
+              <AlertDialogTrigger asChild>
+                <button className="grid size-6 place-items-center rounded text-muted-foreground hover:text-destructive hover:bg-muted cursor-pointer">
+                  <Trash2 className="size-3" />
+                </button>
+              </AlertDialogTrigger>
+              <AlertDialogContent>
+                <AlertDialogHeader>
+                  <AlertDialogTitle>Delete comment?</AlertDialogTitle>
+                  <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+                </AlertDialogHeader>
+                <AlertDialogFooter>
+                  <AlertDialogCancel>Cancel</AlertDialogCancel>
+                  <AlertDialogAction onClick={() => deleteMutation.mutate()}>Delete</AlertDialogAction>
+                </AlertDialogFooter>
+              </AlertDialogContent>
+            </AlertDialog>
+          </div>
+        )}
+      </div>
+
+      {editing ? (
+        <div className="mt-2 ml-7 space-y-2">
+          <Textarea
+            className="min-h-[80px] text-[13px]"
+            value={editBody}
+            onChange={(e) => setEditBody(e.target.value)}
+          />
+          <div className="flex items-center gap-2">
+            <Button className="h-7 px-3 text-[12px]" disabled={saving} onClick={() => { setSaving(true); updateMutation.mutate(); }}>
+              {saving ? "Saving..." : "Update comment"}
+            </Button>
+            <Button className="h-7 px-3 text-[12px]" variant="outline" onClick={() => setEditing(false)}>Cancel</Button>
+          </div>
+        </div>
+      ) : (
+        <div className="mt-1.5 ml-7 text-[13px] text-foreground leading-relaxed whitespace-pre-wrap">
+          {comment.body}
+        </div>
+      )}
+
+      <div className="ml-7 relative">
+        <CommentReactions
+          comment={comment}
+          projectName={projectName}
+          issueNumber={issueNumber}
+          queryKey={queryKey}
+        />
+      </div>
+    </div>
+  );
+}
+
+export default function CommentSection({
+  projectName,
+  issueNumber,
+  currentUsername,
+  queryKey,
+}: {
+  projectName: string;
+  issueNumber: number;
+  currentUsername?: string;
+  queryKey: unknown[];
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [body, setBody] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+
+  const { data: comments = [], isLoading } = useQuery({
+    queryKey: [...queryKey, "comments"],
+    queryFn: async () => {
+      const res = await client.issuesListComments(projectName, issueNumber);
+      return (res.data ?? []) as (IssueCommentResponse & { reactions?: Array<{ id: string; reaction: string; user: IssueAuthor; created_at: string }> })[];
+    },
+    retry: false,
+  });
+
+  const createComment = async (e: FormEvent) => {
+    e.preventDefault();
+    if (!body.trim()) return;
+    setSubmitting(true);
+    try {
+      await client.issuesCreateComment(projectName, issueNumber, { body: body.trim() });
+      setBody("");
+      qc.invalidateQueries({ queryKey: [...queryKey, "comments"] });
+    } catch (err: any) {
+      toast({ title: "Failed to post comment", description: String(err?.message ?? err), variant: "destructive" });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="mt-5">
+      <div className="flex items-center gap-2 mb-3">
+        <MessageSquare className="size-4 text-muted-foreground" />
+        <h2 className="font-heading text-[13px] font-semibold text-foreground">
+          Comments {comments.length > 0 && <span className="font-mono text-[11px] text-muted-foreground">({comments.length})</span>}
+        </h2>
+      </div>
+
+      <form className="mb-4" onSubmit={(e) => void createComment(e)}>
+        <Textarea
+          className="min-h-[80px] text-[13px]"
+          placeholder="Write a comment..."
+          value={body}
+          onChange={(e) => setBody(e.target.value)}
+        />
+        <div className="mt-2 flex items-center justify-between">
+          <span className="text-[11px] text-muted-foreground">Markdown is supported</span>
+          <Button className="h-8 px-4 text-[12px]" disabled={submitting || !body.trim()} type="submit">
+            {submitting ? "Posting..." : "Comment"}
+          </Button>
+        </div>
+      </form>
+
+      {isLoading ? (
+        <div className="space-y-3 py-2">
+          {Array.from({ length: 3 }).map((_, i) => (
+            <div key={i} className="h-16 animate-pulse rounded bg-muted/50" />
+          ))}
+        </div>
+      ) : comments.length > 0 ? (
+        <div className="rounded-md border border-border overflow-hidden">
+          {comments.map((comment) => (
+            <CommentItem
+              key={comment.id}
+              comment={comment}
+              projectName={projectName}
+              issueNumber={issueNumber}
+              queryKey={[...queryKey, "comments"]}
+              currentUsername={currentUsername}
+            />
+          ))}
+        </div>
+      ) : (
+        <div className="rounded-md border border-border px-4 py-6 text-center text-[12px] text-muted-foreground">
+          No comments yet. Start the discussion!
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/page/workspace/issues/detail.tsx b/src/page/workspace/issues/detail.tsx
new file mode 100644
index 0000000..2ef194a
--- /dev/null
+++ b/src/page/workspace/issues/detail.tsx
@@ -0,0 +1,756 @@
+import { useState } from "react";
+import { Link, useParams, useNavigate } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type LabelResponse, type MilestoneResponse, type IssueAuthor, type IssueEventResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@/components/ui/alert-dialog";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import { cn } from "@/lib/utils";
+import { useToast } from "@/hooks/use-toast";
+import { useAuth } from "@/context/auth-context";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import CommentSection from "./comment-section";
+import EditIssueDialog from "./edit-issue-dialog";
+import { LabelManageDialog } from "./label-manage-dialog";
+import { MilestoneManageDialog } from "./milestone-manage-dialog";
+import {
+  Circle,
+  CircleDot,
+  Clock3,
+  GitFork,
+  Pencil,
+  Trash2,
+  Lock,
+  LockOpen,
+  ChevronRight,
+  ExternalLink,
+  Plus,
+  X,
+  Calendar,
+  AlertCircle,
+} from "lucide-react";
+
+// ─── shared helpers ────────────────────────────────────────
+
+function AuthorAvatar({ author }: { author: { username: string; avatar_url?: string | null; display_name?: string | null } }) {
+  const name = author.display_name ?? author.username;
+  return (
+    <span
+      className={cn(
+        "grid size-5 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {author.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={author.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+function LabelBadge({ label }: { label: { name: string; color: string } }) {
+  return (
+    <span
+      className="inline-flex h-[18px] items-center rounded px-1.5 text-[11px] font-medium leading-none whitespace-nowrap"
+      style={{ backgroundColor: label.color + "18", color: label.color }}
+    >
+      {label.name}
+    </span>
+  );
+}
+
+function formatDate(date: string) {
+  return new Date(date).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
+
+function formatRelative(date: string) {
+  const diff = Date.now() - new Date(date).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.floor(hrs / 24);
+  if (days < 30) return `${days}d ago`;
+  return formatDate(date);
+}
+
+function formatEventValue(event: string, value: string | null) {
+  if (!value) return "";
+  if (event === "labeled" || event === "unlabeled") return value;
+  if (event === "milestoned" || event === "demilestoned") return value;
+  if (event === "assigned" || event === "unassigned") return value;
+  if (event === "priority_changed") return value;
+  if (event === "closed" || event === "reopened") return "";
+  return value;
+}
+
+// ─── sidebar section ───────────────────────────────────────
+
+function SidebarSection({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="border-b border-border last:border-b-0 py-3">
+      <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-1.5">{title}</p>
+      {children}
+    </div>
+  );
+}
+
+// ─── assignee picker ───────────────────────────────────────
+
+function AssigneeSection({
+  assignees,
+  projectName,
+  issueNumber,
+  queryKey,
+}: {
+  assignees: IssueAuthor[];
+  projectName: string;
+  issueNumber: number;
+  queryKey: unknown[];
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [open, setOpen] = useState(false);
+
+  const { data: members = [] } = useQuery({
+    queryKey: ["workspace", projectName, "members"],
+    queryFn: async () => {
+      const res = await client.workspaceListMembers(projectName, { limit: 100 } as any);
+      return (res.data ?? []) as Array<{ username: string; display_name?: string | null; avatar_url?: string | null }>;
+    },
+    retry: false,
+  });
+
+  const assignMutation = useMutation({
+    mutationFn: async (username: string) => {
+      await client.issuesAssignUser(projectName, issueNumber, { username });
+    },
+    onSuccess: () => { qc.invalidateQueries({ queryKey }); setOpen(false); },
+    onError: (e: any) => toast({ title: "Failed to assign", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const unassignMutation = useMutation({
+    mutationFn: async (username: string) => {
+      await client.issuesUnassignUser(projectName, issueNumber, { data: { username } } as any);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed to unassign", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const assignedUsernames = new Set(assignees.map((a) => a.username));
+
+  return (
+    <SidebarSection title="Assignees">
+      {assignees.length > 0 ? (
+        <div className="flex flex-wrap items-center gap-1.5">
+          {assignees.map((a) => (
+            <span
+              key={a.username}
+              className="inline-flex items-center gap-1 rounded-full border border-border bg-muted/30 px-2 py-0.5 text-[12px] cursor-pointer hover:border-destructive/30 hover:bg-destructive/5 transition-colors"
+              onClick={() => unassignMutation.mutate(a.username)}
+            >
+              <AuthorAvatar author={a} />
+              <span className="max-w-[80px] truncate">{a.display_name ?? a.username}</span>
+              <X className="size-2.5 text-muted-foreground" />
+            </span>
+          ))}
+        </div>
+      ) : (
+        <span className="text-[12px] text-muted-foreground">No one assigned</span>
+      )}
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button className="mt-1.5 h-7 px-2 text-[11px] w-full justify-start" variant="ghost">
+            <Plus className="size-3 mr-1" /> Assign someone
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-48 p-1" align="start">
+          <ScrollArea className="max-h-48">
+            {members.filter((m) => !assignedUsernames.has(m.username)).map((m) => (
+              <button
+                key={m.username}
+                className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-[12px] text-foreground hover:bg-muted cursor-pointer"
+                onClick={() => assignMutation.mutate(m.username)}
+              >
+                <AuthorAvatar author={m as any} />
+                <span className="truncate">{m.display_name ?? m.username}</span>
+              </button>
+            ))}
+            {members.filter((m) => !assignedUsernames.has(m.username)).length === 0 && (
+              <p className="px-2 py-2 text-[11px] text-muted-foreground">No one available</p>
+            )}
+          </ScrollArea>
+        </PopoverContent>
+      </Popover>
+    </SidebarSection>
+  );
+}
+
+// ─── label sidebar section ─────────────────────────────────
+
+function LabelSection({
+  labels,
+  projectName,
+  issueNumber,
+  queryKey,
+}: {
+  labels: LabelResponse[];
+  projectName: string;
+  issueNumber: number;
+  queryKey: unknown[];
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const [manageOpen, setManageOpen] = useState(false);
+
+  const currentLabelIds = new Set(labels.map((l) => l.id));
+
+  const { data: allLabels = [] } = useQuery({
+    queryKey: ["labels", projectName],
+    queryFn: async () => {
+      const res = await client.issuesListLabels(projectName);
+      return res.data ?? [];
+    },
+    enabled: pickerOpen || manageOpen,
+    retry: false,
+  });
+
+  const addMutation = useMutation({
+    mutationFn: async (labelId: string) => {
+      await client.issuesAddIssueLabel(projectName, issueNumber, { label_id: labelId });
+    },
+    onSuccess: () => { qc.invalidateQueries({ queryKey }); setPickerOpen(false); },
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const removeMutation = useMutation({
+    mutationFn: async (labelId: string) => {
+      await client.issuesRemoveIssueLabel(projectName, issueNumber, { data: { label_id: labelId } } as any);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const availableLabels = allLabels.filter((l) => !currentLabelIds.has(l.id));
+
+  return (
+    <SidebarSection title="Labels">
+      {labels.length > 0 ? (
+        <div className="flex flex-wrap items-center gap-1">
+          {labels.map((label) => (
+            <span
+              key={label.id}
+              className="inline-flex h-[18px] cursor-pointer items-center gap-0.5 rounded px-1.5 text-[11px] font-medium leading-none whitespace-nowrap hover:opacity-80 transition-opacity"
+              style={{ backgroundColor: label.color + "18", color: label.color }}
+              onClick={() => removeMutation.mutate(label.id)}
+            >
+              {label.name} <X className="size-2.5" />
+            </span>
+          ))}
+        </div>
+      ) : (
+        <span className="text-[12px] text-muted-foreground">None yet</span>
+      )}
+      <div className="flex items-center gap-1 mt-1.5">
+        <Popover open={pickerOpen} onOpenChange={setPickerOpen}>
+          <PopoverTrigger asChild>
+            <Button className="h-7 px-2 text-[11px]" variant="ghost">
+              <Plus className="size-3 mr-1" /> Add label
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent className="w-52 p-1" align="start">
+            <ScrollArea className="max-h-48">
+              {availableLabels.length > 0 ? (
+                availableLabels.map((l) => (
+                  <button
+                    key={l.id}
+                    className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-[12px] text-foreground hover:bg-muted cursor-pointer"
+                    onClick={() => addMutation.mutate(l.id)}
+                  >
+                    <span className="h-3 w-3 shrink-0 rounded-full" style={{ backgroundColor: l.color }} />
+                    <span className="truncate">{l.name}</span>
+                  </button>
+                ))
+              ) : (
+                <p className="px-2 py-2 text-[11px] text-muted-foreground">No labels available</p>
+              )}
+            </ScrollArea>
+          </PopoverContent>
+        </Popover>
+        <Button className="h-7 px-2 text-[11px]" variant="ghost" onClick={() => setManageOpen(true)}>
+          <Pencil className="size-3" />
+        </Button>
+      </div>
+      <LabelManageDialog
+        open={manageOpen}
+        onOpenChange={setManageOpen}
+        projectName={projectName}
+        onSelect={(label) => {
+          if (!currentLabelIds.has(label.id)) addMutation.mutate(label.id);
+        }}
+      />
+    </SidebarSection>
+  );
+}
+
+// ─── milestone sidebar section ─────────────────────────────
+
+function MilestoneSection({
+  milestone,
+  projectName,
+  issueNumber,
+  queryKey,
+}: {
+  milestone: MilestoneResponse | null | undefined;
+  projectName: string;
+  issueNumber: number;
+  queryKey: unknown[];
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const [manageOpen, setManageOpen] = useState(false);
+
+  const { data: milestones = [] } = useQuery({
+    queryKey: ["milestones", projectName],
+    queryFn: async () => {
+      const res = await client.issuesListMilestones(projectName);
+      return res.data ?? [];
+    },
+    enabled: pickerOpen || manageOpen,
+    retry: false,
+  });
+
+  const setMutation = useMutation({
+    mutationFn: async (milestoneId: string) => {
+      await client.issuesSetIssueMilestone(projectName, issueNumber, { milestone_id: milestoneId });
+    },
+    onSuccess: () => { qc.invalidateQueries({ queryKey }); setPickerOpen(false); },
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const clearMutation = useMutation({
+    mutationFn: async () => {
+      await client.issuesClearIssueMilestone(projectName, issueNumber);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const openMilestones = milestones.filter((m) => m.state === "open");
+
+  return (
+    <SidebarSection title="Milestone">
+      {milestone ? (
+        <div className="space-y-1">
+          <div className="flex items-center gap-1.5">
+            <span className="text-[12px] font-heading font-medium text-foreground">{milestone.title}</span>
+            <button className="text-muted-foreground hover:text-destructive cursor-pointer" onClick={() => clearMutation.mutate()}>
+              <X className="size-3" />
+            </button>
+          </div>
+          {milestone.due_at && (
+            <span className="font-mono text-[10px] text-muted-foreground">Due {formatDate(milestone.due_at)}</span>
+          )}
+        </div>
+      ) : (
+        <span className="text-[12px] text-muted-foreground">No milestone</span>
+      )}
+      <div className="flex items-center gap-1 mt-1.5">
+        <Popover open={pickerOpen} onOpenChange={setPickerOpen}>
+          <PopoverTrigger asChild>
+            <Button className="h-7 px-2 text-[11px]" variant="ghost">
+              <Plus className="size-3 mr-1" /> Set milestone
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent className="w-52 p-1" align="start">
+            <ScrollArea className="max-h-48">
+              {openMilestones.length > 0 ? (
+                openMilestones.map((m) => (
+                  <button
+                    key={m.id}
+                    className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-[12px] text-foreground hover:bg-muted cursor-pointer"
+                    onClick={() => setMutation.mutate(m.id)}
+                  >
+                    <span className="truncate flex-1 text-left">{m.title}</span>
+                    {m.due_at && <span className="font-mono text-[10px] text-muted-foreground shrink-0">{new Date(m.due_at).toLocaleDateString()}</span>}
+                  </button>
+                ))
+              ) : (
+                <p className="px-2 py-2 text-[11px] text-muted-foreground">No milestones</p>
+              )}
+            </ScrollArea>
+          </PopoverContent>
+        </Popover>
+        <Button className="h-7 px-2 text-[11px]" variant="ghost" onClick={() => setManageOpen(true)}>
+          <Pencil className="size-3" />
+        </Button>
+      </div>
+      <MilestoneManageDialog
+        open={manageOpen}
+        onOpenChange={setManageOpen}
+        projectName={projectName}
+        onSelect={(m) => setMutation.mutate(m.id)}
+      />
+    </SidebarSection>
+  );
+}
+
+// ─── event timeline ────────────────────────────────────────
+
+function EventTimeline({ projectName, issueNumber }: { projectName: string; issueNumber: number }) {
+  const { data: events = [], isLoading } = useQuery({
+    queryKey: ["issue", projectName, issueNumber, "events"],
+    queryFn: async () => {
+      const res = await client.issuesListEvents(projectName, issueNumber);
+      return (res.data ?? []) as IssueEventResponse[];
+    },
+    retry: false,
+  });
+
+  if (isLoading) {
+    return (
+      <div className="mt-5 pt-3 border-t border-border">
+        <p className="text-[11px] text-muted-foreground">Loading events...</p>
+      </div>
+    );
+  }
+
+  if (events.length === 0) return null;
+
+  return (
+    <div className="mt-5 pt-3 border-t border-border">
+      <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-2">Timeline</p>
+      <div className="space-y-2">
+        {events.map((evt, i) => (
+          <div key={i} className="flex items-center gap-2 text-[11px] text-muted-foreground">
+            {evt.actor ? (
+              <span className="flex items-center gap-1">
+                <AuthorAvatar author={evt.actor} />
+                <span className="font-medium text-foreground">{evt.actor.display_name ?? evt.actor.username}</span>
+              </span>
+            ) : (
+              <AlertCircle className="size-3" />
+            )}
+            <span className="capitalize">{evt.event.replace(/_/g, " ")}</span>
+            {evt.to_value && (
+              <>
+                <ChevronRight className="size-3" />
+                <span className="font-medium text-foreground">{formatEventValue(evt.event, evt.to_value)}</span>
+              </>
+            )}
+            <span className="font-mono text-[10px]">{formatRelative(evt.created_at)}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ─── main page ─────────────────────────────────────────────
+
+export default function IssueDetailPage() {
+  const { projectName = "", issueNumber } = useParams();
+  const navigate = useNavigate();
+  const { user } = useAuth();
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const num = Number(issueNumber);
+
+  const [editOpen, setEditOpen] = useState(false);
+
+  const queryKey = ["issue", projectName, num];
+
+  const { data: issue, isLoading } = useQuery({
+    queryKey,
+    queryFn: async () => {
+      const res = await client.issuesGetIssue(projectName, num);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && num > 0,
+    retry: false,
+  });
+
+  const closeMutation = useMutation({
+    mutationFn: async () => {
+      await client.issuesCloseIssue(projectName, num);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed to close", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const reopenMutation = useMutation({
+    mutationFn: async () => {
+      await client.issuesReopenIssue(projectName, num);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey }),
+    onError: (e: any) => toast({ title: "Failed to reopen", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: async () => {
+      await client.issuesDeleteIssue(projectName, num);
+    },
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ["issues", projectName] });
+      navigate(`/${projectName}/issues`);
+    },
+    onError: (e: any) => toast({ title: "Failed to delete", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  if (isLoading) {
+    return (
+      <div className="px-8 py-10 space-y-3">
+        <div className="h-7 animate-pulse rounded bg-muted/50 w-64" />
+        <div className="h-24 animate-pulse rounded bg-muted/50" />
+      </div>
+    );
+  }
+
+  if (!issue) {
+    return (
+      <div className="px-8 py-10 text-center">
+        <p className="text-[13px] text-muted-foreground">Issue not found</p>
+      </div>
+    );
+  }
+
+  const isOpen = issue.state === "open";
+  const currentUsername = user?.username;
+
+  return (
+    <div className="mx-auto max-w-5xl px-8 py-10">
+      {/* Header */}
+      <div className="flex items-start gap-2 justify-between">
+        <div className="flex items-center gap-2 min-w-0">
+          {isOpen ? (
+            <Circle className="size-4 text-green-600 shrink-0" />
+          ) : (
+            <CircleDot className="size-4 text-purple-600 shrink-0" />
+          )}
+          <h1 className="font-heading text-[15px] font-bold text-foreground truncate">{issue.title}</h1>
+          <span className="font-mono text-[12px] text-muted-foreground/60 shrink-0"># {issue.number}</span>
+        </div>
+
+        {/* action buttons */}
+        <div className="flex items-center gap-1.5 shrink-0">
+          {isOpen ? (
+            <Button className="h-8 px-3 text-[12px]" variant="outline" onClick={() => closeMutation.mutate()}>
+              <Lock className="size-3.5 mr-1" />
+              Close issue
+            </Button>
+          ) : (
+            <Button className="h-8 px-3 text-[12px]" variant="outline" onClick={() => reopenMutation.mutate()}>
+              <LockOpen className="size-3.5 mr-1" />
+              Reopen issue
+            </Button>
+          )}
+          <Button className="h-8 px-3 text-[12px]" variant="outline" onClick={() => setEditOpen(true)}>
+            <Pencil className="size-3.5 mr-1" />
+            Edit
+          </Button>
+          <AlertDialog>
+            <AlertDialogTrigger asChild>
+              <Button className="h-8 px-2 text-[12px] text-destructive hover:bg-destructive/10" variant="ghost">
+                <Trash2 className="size-3.5" />
+              </Button>
+            </AlertDialogTrigger>
+            <AlertDialogContent>
+              <AlertDialogHeader>
+                <AlertDialogTitle>Delete &ldquo;{issue.title}&rdquo;?</AlertDialogTitle>
+                <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogCancel>Cancel</AlertDialogCancel>
+                <AlertDialogAction onClick={() => deleteMutation.mutate()}>Delete</AlertDialogAction>
+              </AlertDialogFooter>
+            </AlertDialogContent>
+          </AlertDialog>
+        </div>
+      </div>
+
+      {/* meta row */}
+      <div className="mt-1 flex items-center gap-2 text-[12px] text-muted-foreground">
+        <span className="flex items-center gap-1">
+          <AuthorAvatar author={issue.author} />
+          <span className="font-medium text-foreground">{issue.author.display_name ?? issue.author.username}</span>
+        </span>
+        <span>
+          {isOpen ? "opened" : "closed"} {formatRelative(issue.created_at)}
+        </span>
+        {issue.closed_at && (
+          <span className="flex items-center gap-1"><Clock3 className="size-3" />Closed {formatRelative(issue.closed_at)}</span>
+        )}
+        {issue.priority && (
+          <span className={cn(
+            "font-mono text-[10px] uppercase px-1.5 py-0.5 rounded",
+            issue.priority === "critical" ? "bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-400" :
+            issue.priority === "high" ? "bg-orange-100 text-orange-700 dark:bg-orange-900/30 dark:text-orange-400" :
+            issue.priority === "low" ? "bg-slate-100 text-slate-600 dark:bg-slate-800 dark:text-slate-400" :
+            "bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400",
+          )}>
+            {issue.priority}
+          </span>
+        )}
+        {issue.due_at && (
+          <span className="flex items-center gap-1">
+            <Calendar className="size-3" />
+            Due {formatDate(issue.due_at)}
+          </span>
+        )}
+      </div>
+
+      {/* Body: two-column layout */}
+      <div className="mt-5 grid grid-cols-[1fr_240px] gap-6">
+        {/* Main content */}
+        <div>
+          {issue.labels.length > 0 && (
+            <div className="flex items-center gap-1.5 mb-3">
+              {issue.labels.map((label) => (
+                <LabelBadge key={label.id} label={label} />
+              ))}
+            </div>
+          )}
+
+          {issue.body ? (
+            <div className="rounded-md border border-border overflow-hidden">
+              <div className="flex items-center gap-2 bg-muted/30 px-4 py-2 border-b border-border">
+                <AuthorAvatar author={issue.author} />
+                <span className="font-heading text-[13px] font-medium text-foreground">{issue.author.display_name ?? issue.author.username}</span>
+                <span className="font-mono text-[11px] text-muted-foreground">commented {formatRelative(issue.created_at)}</span>
+              </div>
+              <div className="px-4 py-3 text-[13px] text-foreground whitespace-pre-wrap leading-relaxed">
+                {issue.body}
+              </div>
+            </div>
+          ) : (
+            <div className="rounded-md border border-border px-4 py-6 text-center text-[12px] text-muted-foreground">
+              No description provided.
+            </div>
+          )}
+
+          {/* Linked pull requests */}
+          {issue.pull_requests.length > 0 && (
+            <div className="mt-5">
+              <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-2">Linked pull requests</p>
+              <div className="space-y-1.5">
+                {issue.pull_requests.map((pr) => (
+                  <Link
+                    key={pr.id}
+                    to={`/${projectName}/repos/${pr.title}/pulls/${pr.number}`}
+                    className="flex items-center gap-2 rounded-md border border-border px-3 py-2 hover:bg-muted/50 transition-colors cursor-pointer"
+                  >
+                    <GitFork className="size-3.5 text-muted-foreground shrink-0" />
+                    <span className="font-heading text-[13px] font-medium text-foreground truncate">{pr.title}</span>
+                    <span className="font-mono text-[11px] text-muted-foreground shrink-0"># {pr.number}</span>
+                    <span className={cn("font-mono text-[10px] shrink-0", pr.state === "open" ? "text-green-600" : "text-purple-600")}>
+                      {pr.state}
+                    </span>
+                    <ExternalLink className="size-3 text-muted-foreground shrink-0" />
+                  </Link>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Linked repos */}
+          {issue.repos.length > 0 && (
+            <div className="mt-5">
+              <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-2">Linked repositories</p>
+              <div className="space-y-1.5">
+                {issue.repos.map((repo) => (
+                  <Link
+                    key={repo.id}
+                    to={`/${projectName}/repos/${repo.name}`}
+                    className="flex items-center gap-2 rounded-md border border-border px-3 py-2 hover:bg-muted/50 transition-colors cursor-pointer"
+                  >
+                    <GitFork className="size-3.5 text-muted-foreground shrink-0" />
+                    <span className="font-heading text-[13px] font-medium text-foreground">{repo.name}</span>
+                    <ExternalLink className="size-3 text-muted-foreground shrink-0 ml-auto" />
+                  </Link>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Comments section */}
+          <CommentSection
+            projectName={projectName}
+            issueNumber={num}
+            currentUsername={currentUsername}
+            queryKey={queryKey}
+          />
+
+          {/* Event Timeline */}
+          <EventTimeline projectName={projectName} issueNumber={num} />
+        </div>
+
+        {/* Sidebar */}
+        <div className="rounded-md border border-border overflow-hidden">
+          <AssigneeSection
+            assignees={issue.assignees}
+            projectName={projectName}
+            issueNumber={num}
+            queryKey={queryKey}
+          />
+
+          <LabelSection
+            labels={issue.labels}
+            projectName={projectName}
+            issueNumber={num}
+            queryKey={queryKey}
+          />
+
+          <MilestoneSection
+            milestone={issue.milestone}
+            projectName={projectName}
+            issueNumber={num}
+            queryKey={queryKey}
+          />
+
+          <SidebarSection title="Priority">
+            <span className={cn(
+              "text-[12px] font-heading font-medium capitalize",
+              issue.priority === "critical" ? "text-red-600" :
+              issue.priority === "high" ? "text-orange-600" :
+              issue.priority === "low" ? "text-muted-foreground" :
+              "text-foreground",
+            )}>
+              {issue.priority ?? "None"}
+            </span>
+          </SidebarSection>
+
+          {issue.due_at && (
+            <SidebarSection title="Due date">
+              <span className="text-[12px] text-foreground">{formatDate(issue.due_at)}</span>
+            </SidebarSection>
+          )}
+        </div>
+      </div>
+
+      {/* Edit dialog */}
+      <EditIssueDialog
+        open={editOpen}
+        onOpenChange={setEditOpen}
+        issue={issue}
+        projectName={projectName}
+        queryKey={queryKey}
+      />
+    </div>
+  );
+}
diff --git a/src/page/workspace/issues/edit-issue-dialog.tsx b/src/page/workspace/issues/edit-issue-dialog.tsx
new file mode 100644
index 0000000..c42a910
--- /dev/null
+++ b/src/page/workspace/issues/edit-issue-dialog.tsx
@@ -0,0 +1,115 @@
+import { useState, type FormEvent } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { client, type IssueResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogClose } from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { useToast } from "@/hooks/use-toast";
+
+export default function EditIssueDialog({
+  open,
+  onOpenChange,
+  issue,
+  projectName,
+  queryKey,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  issue: IssueResponse;
+  projectName: string;
+  queryKey: unknown[];
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setSubmitting(true);
+    const form = new FormData(e.currentTarget);
+    const title = (form.get("title") as string) || null;
+    const body = (form.get("body") as string) || null;
+    const priority = (form.get("priority") as string) || null;
+    const dueAt = (form.get("due_at") as string) || null;
+
+    try {
+      await client.issuesUpdateIssue(projectName, issue.number, {
+        title,
+        body,
+        priority,
+        due_at: dueAt,
+      });
+      qc.invalidateQueries({ queryKey });
+      onOpenChange(false);
+    } catch (err: any) {
+      toast({ title: "Failed to update issue", description: String(err?.message ?? err), variant: "destructive" });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-xl">
+        <DialogHeader>
+          <DialogTitle>Edit issue # {issue.number}</DialogTitle>
+        </DialogHeader>
+        <form className="space-y-4" onSubmit={(e) => void handleSubmit(e)}>
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Title</label>
+            <Input
+              className="mt-1 h-9 text-[14px] font-heading font-semibold"
+              name="title"
+              defaultValue={issue.title}
+              required
+            />
+          </div>
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Description</label>
+            <Textarea
+              className="mt-1 min-h-[150px] text-[13px]"
+              name="body"
+              defaultValue={issue.body ?? ""}
+              placeholder="Leave a comment... Markdown is supported"
+            />
+          </div>
+          <div className="grid grid-cols-2 gap-3">
+            <div>
+              <label className="text-[12px] font-medium text-foreground">Priority</label>
+              <Select name="priority" defaultValue={issue.priority ?? "normal"}>
+                <SelectTrigger className="mt-1 w-full h-8 text-[12px]">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="critical">Critical</SelectItem>
+                  <SelectItem value="high">High</SelectItem>
+                  <SelectItem value="normal">Normal</SelectItem>
+                  <SelectItem value="low">Low</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+            <div>
+              <label className="text-[12px] font-medium text-foreground">Due date</label>
+              <Input
+                className="mt-1 h-8 w-full text-[12px]"
+                name="due_at"
+                type="date"
+                defaultValue={issue.due_at ? issue.due_at.slice(0, 10) : ""}
+              />
+            </div>
+          </div>
+          <div className="flex items-center justify-end gap-2 pt-2">
+            <DialogClose asChild>
+              <Button className="h-8 px-3 text-[12px]" variant="outline">Cancel</Button>
+            </DialogClose>
+            <Button className="h-8 px-3 text-[12px]" disabled={submitting} type="submit">
+              {submitting ? "Saving..." : "Save changes"}
+            </Button>
+          </div>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/page/workspace/issues/index.tsx b/src/page/workspace/issues/index.tsx
new file mode 100644
index 0000000..65128ac
--- /dev/null
+++ b/src/page/workspace/issues/index.tsx
@@ -0,0 +1,305 @@
+import { useState, type FormEvent } from "react";
+import { Link, useParams } from "react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { client, type IssueResponse } from "@/client";
+import {
+  Circle,
+  CircleDot,
+  GitFork,
+  MessageSquare,
+  Plus,
+  Search,
+  Tag,
+  Milestone,
+  User,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import { LabelManageDialog } from "./label-manage-dialog";
+import { MilestoneManageDialog } from "./milestone-manage-dialog";
+
+function formatDate(date: string) {
+  const now = new Date();
+  const d = new Date(date);
+  const diff = now.getTime() - d.getTime();
+  const days = Math.floor(diff / 86400000);
+  if (days < 1) return "today";
+  if (days === 1) return "1 day ago";
+  if (days < 30) return `${days} days ago`;
+  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
+  return `${Math.floor(days / 365)}y ago`;
+}
+
+function AuthorAvatar({ author }: { author: { username: string; avatar_url?: string | null; display_name?: string | null } }) {
+  const name = author.display_name ?? author.username;
+  return (
+    <span
+      className={cn(
+        "grid size-5 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {author.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={author.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+function LabelBadge({ label }: { label: { name: string; color: string } }) {
+  return (
+    <span
+      className="inline-flex h-[18px] items-center rounded px-1.5 text-[11px] font-medium leading-none whitespace-nowrap"
+      style={{ backgroundColor: label.color + "18", color: label.color }}
+    >
+      {label.name}
+    </span>
+  );
+}
+
+function IssueRow({ issue, projectName }: { issue: IssueResponse; projectName: string }) {
+  const isOpen = issue.state === "open";
+  return (
+    <Link
+      className="group flex items-start gap-3 border-b border-border px-4 py-2.5 last:border-b-0 transition-colors hover:bg-muted/40"
+      to={`/${projectName}/issues/${issue.number}`}
+    >
+      <span className="mt-0.5 shrink-0">
+        {isOpen ? <Circle className="size-[14px] text-green-600" /> : <CircleDot className="size-[14px] text-purple-600" />}
+      </span>
+      <div className="min-w-0 flex-1">
+        <div className="flex items-baseline gap-1.5 flex-wrap">
+          <span className="font-heading text-[13px] font-semibold text-foreground leading-tight">{issue.title}</span>
+          <span className="font-mono text-[11px] text-muted-foreground/60"># {issue.number}</span>
+          {issue.labels.map((label) => <LabelBadge key={label.id} label={label} />)}
+        </div>
+        <div className="mt-0.5 flex items-center gap-2 text-[11px] text-muted-foreground">
+          <span className="flex items-center gap-1">
+            <AuthorAvatar author={issue.author} />
+            {issue.author.display_name ?? issue.author.username}
+          </span>
+          <span>opened {formatDate(issue.created_at)}</span>
+          {issue.milestone && (
+            <span className="flex items-center gap-0.5">
+              <Milestone className="size-[10px]" />
+              {issue.milestone.title}
+            </span>
+          )}
+          {issue.assignees.length > 0 && <span className="flex items-center gap-0.5"><User className="size-[10px]" />{issue.assignees.length}</span>}
+          {issue.pull_requests.length > 0 && <span className="flex items-center gap-0.5"><GitFork className="size-[10px]" />{issue.pull_requests.length}</span>}
+        </div>
+      </div>
+    </Link>
+  );
+}
+
+function IssueListView({ projectName, onCreate }: { projectName: string; onCreate: () => void }) {
+  const [stateFilter, setStateFilter] = useState<string>("open");
+  const [search, setSearch] = useState("");
+  const [labelManOpen, setLabelManOpen] = useState(false);
+  const [mileManOpen, setMileManOpen] = useState(false);
+
+  const { data: issues = [], isLoading } = useQuery({
+    queryKey: ["issues", projectName, stateFilter],
+    queryFn: async () => {
+      const res = await client.issuesListIssues(projectName, { state: stateFilter });
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const filteredIssues = search
+    ? issues.filter((i) => i.title.toLowerCase().includes(search.toLowerCase()) || String(i.number).includes(search))
+    : issues;
+
+  const openCount = issues.filter((i) => i.state === "open").length;
+  const closedCount = issues.filter((i) => i.state === "closed").length;
+
+  return (
+    <>
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <h1 className="font-heading text-lg font-bold text-foreground">Issues</h1>
+          {/* label & milestone manage buttons */}
+          <Button className="h-7 px-2 text-[11px]" variant="ghost" onClick={() => setLabelManOpen(true)}>
+            <Tag className="size-3.5 mr-1" />
+            Labels
+          </Button>
+          <Button className="h-7 px-2 text-[11px]" variant="ghost" onClick={() => setMileManOpen(true)}>
+            <Milestone className="size-3.5 mr-1" />
+            Milestones
+          </Button>
+        </div>
+        <Button className="h-8 rounded px-3 text-[13px]" onClick={onCreate}>
+          <Plus className="size-3.5 mr-1" />New issue
+        </Button>
+      </div>
+
+      <div className="mt-6 rounded-md border border-border overflow-hidden">
+        <div className="flex items-center gap-2 bg-muted/50 px-3 py-2 border-b border-border">
+          <nav className="flex items-center">
+            {[
+              { key: "open", icon: <Circle className="size-3 text-green-600" />, count: openCount },
+              { key: "closed", icon: <CircleDot className="size-3 text-purple-600" />, count: closedCount },
+              { key: "all", icon: null, count: issues.length },
+            ].map((tab) => (
+              <button
+                className={cn("flex items-center gap-1.5 px-2.5 py-1 text-[12px] font-medium transition-colors", stateFilter === tab.key ? "text-foreground" : "text-muted-foreground hover:text-foreground")}
+                key={tab.key}
+                onClick={() => setStateFilter(tab.key)}
+              >
+                {tab.icon}
+                {tab.key === "all" ? "All" : tab.key.charAt(0).toUpperCase() + tab.key.slice(1)}
+                <span className="font-mono text-[10px] text-muted-foreground">{tab.count}</span>
+              </button>
+            ))}
+          </nav>
+          <div className="ml-auto relative">
+            <Search className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+            <Input className="h-7 w-52 rounded-sm border-border bg-card pl-7 text-[12px]" placeholder="Filter issues..." value={search} onChange={(e) => setSearch(e.target.value)} />
+          </div>
+        </div>
+        {isLoading ? (
+          <div className="px-4 py-2">
+            {Array.from({ length: 5 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}
+          </div>
+        ) : filteredIssues.length > 0 ? (
+          <div>{filteredIssues.map((issue) => <IssueRow key={issue.number} issue={issue} projectName={projectName} />)}</div>
+        ) : (
+          <div className="py-12 text-center">
+            <MessageSquare className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-3 text-[13px] text-muted-foreground">{stateFilter === "open" ? "No open issues" : stateFilter === "closed" ? "No closed issues" : "No issues yet"}</p>
+          </div>
+        )}
+      </div>
+
+      {/* Label & Milestone management dialogs */}
+      <LabelManageDialog open={labelManOpen} onOpenChange={setLabelManOpen} projectName={projectName} />
+      <MilestoneManageDialog open={mileManOpen} onOpenChange={setMileManOpen} projectName={projectName} />
+    </>
+  );
+}
+
+function IssueCreateView({ projectName, onCancel }: { projectName: string; onCancel: () => void }) {
+  const qc = useQueryClient();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const [priority, setPriority] = useState("normal");
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+    const title = form.get("title") as string;
+    const body = (form.get("body") as string) || null;
+    const dueAt = (form.get("due_at") as string) || null;
+
+    if (!title.trim()) {
+      setError("Title is required.");
+      setSubmitting(false);
+      return;
+    }
+
+    try {
+      await client.issuesCreateIssue(projectName, {
+        title: title.trim(),
+        body,
+        priority,
+        due_at: dueAt,
+      });
+      await qc.invalidateQueries({ queryKey: ["issues", projectName] });
+      onCancel();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to create issue.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <>
+      <h1 className="font-heading text-lg font-bold text-foreground">New issue</h1>
+
+      <form className="mt-6 grid grid-cols-[1fr_240px] gap-6" onSubmit={(e) => void handleSubmit(e)}>
+        <div className="space-y-4">
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Title</label>
+            <Input
+              className="mt-1.5 h-9 text-[14px] font-heading font-semibold"
+              name="title"
+              placeholder="Issue title"
+              required
+              autoFocus
+            />
+          </div>
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Description</label>
+            <Textarea
+              className="mt-1.5 min-h-[200px] text-[13px]"
+              name="body"
+              placeholder="Leave a comment... Markdown is supported"
+            />
+          </div>
+          {error && <p className="text-[12px] text-destructive">{error}</p>}
+          <div className="flex items-center gap-3">
+            <Button className="h-9 px-4 text-[13px]" disabled={submitting} type="submit">
+              {submitting ? "Submitting..." : "Submit new issue"}
+            </Button>
+            <Button className="h-9 px-4 text-[13px]" onClick={onCancel} variant="outline">Cancel</Button>
+          </div>
+        </div>
+
+        <div className="space-y-4">
+          <div>
+            <label className="text-[12px] font-medium text-foreground">Priority</label>
+            <Select value={priority} onValueChange={(v) => setPriority(v ?? "normal")}>
+              <SelectTrigger className="mt-1 w-full h-8 text-[12px]">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="critical">Critical</SelectItem>
+                <SelectItem value="high">High</SelectItem>
+                <SelectItem value="normal">Normal</SelectItem>
+                <SelectItem value="low">Low</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div>
+            <label className="text-[12px] font-medium text-foreground">Due date <span className="text-muted-foreground">(optional)</span></label>
+            <Input className="mt-1 h-8 w-full text-[12px]" name="due_at" placeholder="e.g. 2026-06-30" type="date" />
+          </div>
+        </div>
+      </form>
+    </>
+  );
+}
+
+export default function WorkspaceIssuesPage() {
+  const { projectName = "" } = useParams();
+  const [mode, setMode] = useState<"list" | "create">("list");
+
+  return (
+    <div className="px-8 py-10">
+      {mode === "list" ? (
+        <IssueListView projectName={projectName} onCreate={() => setMode("create")} />
+      ) : (
+        <IssueCreateView projectName={projectName} onCancel={() => setMode("list")} />
+      )}
+    </div>
+  );
+}
diff --git a/src/page/workspace/issues/label-manage-dialog.tsx b/src/page/workspace/issues/label-manage-dialog.tsx
new file mode 100644
index 0000000..15981ca
--- /dev/null
+++ b/src/page/workspace/issues/label-manage-dialog.tsx
@@ -0,0 +1,214 @@
+import { useState, type FormEvent } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type LabelResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger } from "@/components/ui/alert-dialog";
+import { useToast } from "@/hooks/use-toast";
+import { cn } from "@/lib/utils";
+import { Pencil, Plus, Trash2, X } from "lucide-react";
+
+const PRESET_COLORS = [
+  "#EF4444", "#F97316", "#F59E0B", "#22C55E", "#14B8A6",
+  "#3B82F6", "#6366F1", "#A855F7", "#EC4899", "#78716C",
+  "#DC2626", "#EA580C", "#D97706", "#16A34A", "#0D9488",
+  "#2563EB", "#4F46E5", "#9333EA", "#DB2777", "#57534E",
+];
+
+function LabelManageDialog({
+  open,
+  onOpenChange,
+  projectName,
+  onSelect,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  projectName: string;
+  onSelect?: (label: LabelResponse) => void;
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [showForm, setShowForm] = useState(false);
+  const [editId, setEditId] = useState<string | null>(null);
+
+  const queryKey = ["labels", projectName];
+  const { data: labels = [] } = useQuery({
+    queryKey,
+    queryFn: async () => {
+      const res = await client.issuesListLabels(projectName);
+      return res.data ?? [];
+    },
+    enabled: open,
+    retry: false,
+  });
+
+  const invalidate = () => qc.invalidateQueries({ queryKey });
+
+  const createMutation = useMutation({
+    mutationFn: async (data: { name: string; color: string; description?: string | null }) => {
+      await client.issuesCreateLabel(projectName, data);
+    },
+    onSuccess: () => { invalidate(); setShowForm(false); },
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const updateMutation = useMutation({
+    mutationFn: async ({ id, ...data }: { id: string; name?: string; color?: string; description?: string | null }) => {
+      await client.issuesUpdateLabel(projectName, id, data);
+    },
+    onSuccess: () => { invalidate(); setEditId(null); },
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: async (id: string) => {
+      await client.issuesDeleteLabel(projectName, id);
+    },
+    onSuccess: () => invalidate(),
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-md">
+        <DialogHeader className="flex flex-row items-center justify-between">
+          <DialogTitle>Manage labels</DialogTitle>
+          <Button className="h-7 px-2 text-[12px]" variant="ghost" onClick={() => setShowForm(true)}>
+            <Plus className="size-3.5" />
+          </Button>
+        </DialogHeader>
+
+        {showForm && (
+          <LabelForm
+            onSubmit={(data) => createMutation.mutate(data)}
+            onCancel={() => setShowForm(false)}
+            submitting={createMutation.isPending}
+          />
+        )}
+
+        <div className="max-h-[300px] space-y-1 overflow-y-auto">
+          {labels.length === 0 && !showForm && (
+            <p className="text-center text-[12px] text-muted-foreground py-4">No labels yet</p>
+          )}
+          {labels.map((label) => (
+            <div key={label.id}>
+              {editId === label.id ? (
+                <LabelForm
+                  initialName={label.name}
+                  initialColor={label.color}
+                  initialDescription={label.description}
+                  onSubmit={(data) => updateMutation.mutate({ id: label.id, ...data })}
+                  onCancel={() => setEditId(null)}
+                  submitting={updateMutation.isPending}
+                />
+              ) : (
+                <div className="flex items-center gap-2 rounded py-1 px-1 hover:bg-muted/50">
+                  <span
+                    className="h-4 w-4 shrink-0 rounded-full"
+                    style={{ backgroundColor: label.color }}
+                  />
+                  <span className="flex-1 text-[12px] font-heading font-medium text-foreground">
+                    {label.name}
+                  </span>
+                  {onSelect && (
+                    <Button className="h-6 px-2 text-[11px]" variant="ghost" onClick={() => { onSelect(label); onOpenChange(false); }}>
+                      Select
+                    </Button>
+                  )}
+                  <button className="grid size-6 place-items-center rounded text-muted-foreground hover:text-foreground cursor-pointer" onClick={() => setEditId(label.id)}>
+                    <Pencil className="size-3" />
+                  </button>
+                  <AlertDialog>
+                    <AlertDialogTrigger asChild>
+                      <button className="grid size-6 place-items-center rounded text-muted-foreground hover:text-destructive cursor-pointer">
+                        <Trash2 className="size-3" />
+                      </button>
+                    </AlertDialogTrigger>
+                    <AlertDialogContent>
+                      <AlertDialogHeader>
+                        <AlertDialogTitle>Delete label &ldquo;{label.name}&rdquo;?</AlertDialogTitle>
+                        <AlertDialogDescription>This will remove it from all issues.</AlertDialogDescription>
+                      </AlertDialogHeader>
+                      <AlertDialogFooter>
+                        <AlertDialogCancel>Cancel</AlertDialogCancel>
+                        <AlertDialogAction onClick={() => deleteMutation.mutate(label.id)}>Delete</AlertDialogAction>
+                      </AlertDialogFooter>
+                    </AlertDialogContent>
+                  </AlertDialog>
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function LabelForm({
+  initialName = "",
+  initialColor = "#3B82F6",
+  initialDescription = "",
+  onSubmit,
+  onCancel,
+  submitting,
+}: {
+  initialName?: string;
+  initialColor?: string;
+  initialDescription?: string | null;
+  onSubmit: (data: { name: string; color: string; description?: string | null }) => void;
+  onCancel: () => void;
+  submitting: boolean;
+}) {
+  const [color, setColor] = useState(initialColor);
+
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const form = new FormData(e.currentTarget);
+    const name = (form.get("name") as string).trim();
+    const description = (form.get("description") as string)?.trim() || null;
+    if (!name) return;
+    onSubmit({ name, color, description });
+  };
+
+  return (
+    <form className="rounded border border-border p-3 mb-2 space-y-2 bg-muted/20" onSubmit={(e) => void handleSubmit(e)}>
+      <div className="flex items-center gap-2">
+        <Input className="h-8 text-[12px]" name="name" placeholder="Label name" defaultValue={initialName} required autoFocus />
+        <div className="flex items-center gap-0.5">
+          {PRESET_COLORS.slice(0, 8).map((c) => (
+            <button
+              key={c}
+              type="button"
+              className={cn("h-6 w-6 rounded border-2 cursor-pointer", color === c ? "border-foreground" : "border-transparent")}
+              style={{ backgroundColor: c }}
+              onClick={() => setColor(c)}
+            />
+          ))}
+        </div>
+      </div>
+      <Input className="h-8 text-[12px]" name="description" placeholder="Description (optional)" defaultValue={initialDescription ?? ""} />
+      <div className="flex items-center gap-2">
+        {PRESET_COLORS.slice(8).map((c) => (
+          <button
+            key={c}
+            type="button"
+            className={cn("h-6 w-6 rounded border-2 cursor-pointer", color === c ? "border-foreground" : "border-transparent")}
+            style={{ backgroundColor: c }}
+            onClick={() => setColor(c)}
+          />
+        ))}
+        <div className="flex-1" />
+        <Button className="h-7 px-3 text-[11px]" variant="outline" type="button" onClick={onCancel}>
+          <X className="size-3" />
+        </Button>
+        <Button className="h-7 px-3 text-[11px]" disabled={submitting} type="submit">
+          {submitting ? "Saving..." : "Save"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+
+export { LabelManageDialog };
diff --git a/src/page/workspace/issues/milestone-manage-dialog.tsx b/src/page/workspace/issues/milestone-manage-dialog.tsx
new file mode 100644
index 0000000..8cb5d8d
--- /dev/null
+++ b/src/page/workspace/issues/milestone-manage-dialog.tsx
@@ -0,0 +1,210 @@
+import { useState, type FormEvent } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type MilestoneResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@/components/ui/alert-dialog";
+import { useToast } from "@/hooks/use-toast";
+import { Milestone, Pencil, Plus, Trash2, X } from "lucide-react";
+
+function MilestoneManageDialog({
+  open,
+  onOpenChange,
+  projectName,
+  onSelect,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  projectName: string;
+  onSelect?: (milestone: MilestoneResponse) => void;
+}) {
+  const qc = useQueryClient();
+  const { toast } = useToast();
+  const [showForm, setShowForm] = useState(false);
+  const [editId, setEditId] = useState<string | null>(null);
+
+  const queryKey = ["milestones", projectName];
+  const { data: milestones = [] } = useQuery({
+    queryKey,
+    queryFn: async () => {
+      const res = await client.issuesListMilestones(projectName);
+      return res.data ?? [];
+    },
+    enabled: open,
+    retry: false,
+  });
+
+  const invalidate = () => qc.invalidateQueries({ queryKey });
+
+  const createMutation = useMutation({
+    mutationFn: async (data: { title: string; description?: string | null; due_at?: string | null }) => {
+      await client.issuesCreateMilestone(projectName, data);
+    },
+    onSuccess: () => { invalidate(); setShowForm(false); },
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const updateMutation = useMutation({
+    mutationFn: async ({ id, ...data }: { id: string; title?: string; description?: string | null; due_at?: string | null; state?: string }) => {
+      await client.issuesUpdateMilestone(projectName, id, data);
+    },
+    onSuccess: () => { invalidate(); setEditId(null); },
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: async (id: string) => {
+      await client.issuesDeleteMilestone(projectName, id);
+    },
+    onSuccess: () => invalidate(),
+    onError: (e: any) => toast({ title: "Failed", description: String(e?.message ?? e), variant: "destructive" }),
+  });
+
+  const openMilestones = milestones.filter((m) => m.state === "open");
+  const closedMilestones = milestones.filter((m) => m.state === "closed");
+
+  const renderList = (items: MilestoneResponse[], _closed: boolean) =>
+    items.map((m) => (
+      <div key={m.id}>
+        {editId === m.id ? (
+          <MilestoneForm
+            initialTitle={m.title}
+            initialDescription={m.description}
+            initialDueAt={m.due_at}
+            onSubmit={(data) => updateMutation.mutate({ id: m.id, ...data })}
+            onCancel={() => setEditId(null)}
+            submitting={updateMutation.isPending}
+          />
+        ) : (
+          <div className="flex items-center gap-2 rounded py-1.5 px-1 hover:bg-muted/50">
+            <Milestone className="size-4 shrink-0 text-muted-foreground" />
+            <div className="flex-1 min-w-0">
+              <span className="text-[12px] font-heading font-medium text-foreground">{m.title}</span>
+              {m.due_at && (
+                <span className="ml-2 font-mono text-[10px] text-muted-foreground">
+                  Due {new Date(m.due_at).toLocaleDateString()}
+                </span>
+              )}
+              {m.description && <p className="text-[11px] text-muted-foreground truncate">{m.description}</p>}
+            </div>
+            {onSelect && (
+              <Button className="h-6 px-2 text-[11px]" variant="ghost" onClick={() => { onSelect(m); onOpenChange(false); }}>
+                Select
+              </Button>
+            )}
+            <button className="grid size-6 place-items-center rounded text-muted-foreground hover:text-foreground cursor-pointer" onClick={() => setEditId(m.id)}>
+              <Pencil className="size-3" />
+            </button>
+            <AlertDialog>
+              <AlertDialogTrigger asChild>
+                <button className="grid size-6 place-items-center rounded text-muted-foreground hover:text-destructive cursor-pointer">
+                  <Trash2 className="size-3" />
+                </button>
+              </AlertDialogTrigger>
+              <AlertDialogContent>
+                <AlertDialogHeader>
+                  <AlertDialogTitle>Delete &ldquo;{m.title}&rdquo;?</AlertDialogTitle>
+                  <AlertDialogDescription>This will remove it from all issues.</AlertDialogDescription>
+                </AlertDialogHeader>
+                <AlertDialogFooter>
+                  <AlertDialogCancel>Cancel</AlertDialogCancel>
+                  <AlertDialogAction onClick={() => deleteMutation.mutate(m.id)}>Delete</AlertDialogAction>
+                </AlertDialogFooter>
+              </AlertDialogContent>
+            </AlertDialog>
+          </div>
+        )}
+      </div>
+    ));
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-md">
+        <DialogHeader className="flex flex-row items-center justify-between">
+          <DialogTitle>Manage milestones</DialogTitle>
+          <Button className="h-7 px-2 text-[12px]" variant="ghost" onClick={() => setShowForm(true)}>
+            <Plus className="size-3.5" />
+          </Button>
+        </DialogHeader>
+
+        {showForm && (
+          <MilestoneForm
+            onSubmit={(data) => createMutation.mutate(data)}
+            onCancel={() => setShowForm(false)}
+            submitting={createMutation.isPending}
+          />
+        )}
+
+        <div className="max-h-[350px] space-y-1 overflow-y-auto">
+          {milestones.length === 0 && !showForm && (
+            <p className="text-center text-[12px] text-muted-foreground py-4">No milestones yet</p>
+          )}
+          {renderList(openMilestones, false)}
+          {closedMilestones.length > 0 && (
+            <>
+              <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mt-2 mb-1 px-1">Closed</p>
+              {renderList(closedMilestones, true)}
+            </>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function MilestoneForm({
+  initialTitle = "",
+  initialDescription = "",
+  initialDueAt = "",
+  onSubmit,
+  onCancel,
+  submitting,
+}: {
+  initialTitle?: string;
+  initialDescription?: string | null;
+  initialDueAt?: string | null;
+  onSubmit: (data: { title: string; description?: string | null; due_at?: string | null }) => void;
+  onCancel: () => void;
+  submitting: boolean;
+}) {
+  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const form = new FormData(e.currentTarget);
+    const title = (form.get("title") as string).trim();
+    const description = (form.get("description") as string)?.trim() || null;
+    const dueAt = (form.get("due_at") as string) || null;
+    if (!title) return;
+    onSubmit({ title, description, due_at: dueAt });
+  };
+
+  return (
+    <form className="rounded border border-border p-3 mb-2 space-y-2 bg-muted/20" onSubmit={(e) => void handleSubmit(e)}>
+      <div className="flex items-center gap-2">
+        <Input className="h-8 text-[12px]" name="title" placeholder="Milestone title" defaultValue={initialTitle} required autoFocus />
+      </div>
+      <Input className="h-8 text-[12px]" name="description" placeholder="Description (optional)" defaultValue={initialDescription ?? ""} />
+      <Input className="h-8 text-[12px]" name="due_at" type="date" defaultValue={initialDueAt ? initialDueAt.slice(0, 10) : ""} />
+      <div className="flex items-center justify-end gap-2">
+        <Button className="h-7 px-3 text-[11px]" variant="outline" type="button" onClick={onCancel}>
+          <X className="size-3" />
+        </Button>
+        <Button className="h-7 px-3 text-[11px]" disabled={submitting} type="submit">
+          {submitting ? "Saving..." : "Save"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+
+export { MilestoneManageDialog };
diff --git a/src/page/workspace/placeholder.tsx b/src/page/workspace/placeholder.tsx
new file mode 100644
index 0000000..0c98ca0
--- /dev/null
+++ b/src/page/workspace/placeholder.tsx
@@ -0,0 +1,25 @@
+import { useLocation } from "react-router";
+
+function titleFromPath(pathname: string) {
+  const segment = pathname.split("/").filter(Boolean).at(-1) ?? "workspace";
+  return segment
+    .split("-")
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+export default function WorkspacePlaceholderPage() {
+  const location = useLocation();
+  const title = titleFromPath(location.pathname);
+
+  return (
+    <div className="flex h-full items-center justify-center px-8 py-10">
+      <div className="text-center">
+        <h1 className="text-2xl font-heading font-semibold text-foreground">{title}</h1>
+        <p className="mt-3 text-base text-muted-foreground">
+          This section is ready for content.
+        </p>
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/branches.tsx b/src/page/workspace/repo/branches.tsx
new file mode 100644
index 0000000..872e76f
--- /dev/null
+++ b/src/page/workspace/repo/branches.tsx
@@ -0,0 +1,195 @@
+import { useState } from "react";
+import { useParams } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { GitBranch, Search, Plus, Trash2, Pencil } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+export default function BranchesTab() {
+  const { projectName = "", repoName = "" } = useParams();
+
+  const { data: repoData } = useQuery({
+    queryKey: ["repo", projectName, repoName],
+    queryFn: async () => {
+      const res = await client.gitGetRepo(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const defaultBranch = repoData?.default_branch ?? "main";
+
+  const qc = useQueryClient();
+  const [search, setSearch] = useState("");
+  const [showCreate, setShowCreate] = useState(false);
+  const [newBranchName, setNewBranchName] = useState("");
+  const [newBranchSource, setNewBranchSource] = useState(defaultBranch);
+  const [renaming, setRenaming] = useState<string | null>(null);
+  const [renameValue, setRenameValue] = useState("");
+
+  const { data: branches = [], isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branches"],
+    queryFn: async () => {
+      const res = await client.gitListBranches(projectName, repoName);
+      return res.data.branches;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const createBranch = useMutation({
+    mutationFn: async () => { await client.gitForkBranch(projectName, repoName, { name: newBranchName, oid: newBranchSource } as any); },
+    onSuccess: () => { setShowCreate(false); setNewBranchName(""); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "branches"] }); },
+  });
+
+  const deleteBranch = useMutation({
+    mutationFn: async (name: string) => { await client.gitDeleteBranch(projectName, repoName, name); },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "branches"] }),
+  });
+
+  const renameBranch = useMutation({
+    mutationFn: async ({ oldName, newName }: { oldName: string; newName: string }) => { await (client as any).gitRenameBranch(projectName, repoName, oldName, { new_branch: newName }); },
+    onSuccess: () => { setRenaming(null); setRenameValue(""); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "branches"] }); },
+  });
+
+  const filtered = search ? branches.filter((b) => b.name.toLowerCase().includes(search.toLowerCase())) : branches;
+  const defaultBranches = filtered.filter((b) => b.name === defaultBranch);
+  const otherBranches = filtered.filter((b) => b.name !== defaultBranch);
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center gap-2">
+        <div className="relative flex-1 max-w-[300px]">
+          <Search className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+          <Input className="h-7 w-full rounded-sm border-border bg-card pl-7 text-[12px]" placeholder="Find a branch..." value={search} onChange={(e) => setSearch(e.target.value)} />
+        </div>
+        <Button className="h-7 px-2 text-[12px] ml-auto" onClick={() => setShowCreate(!showCreate)}>
+          <Plus className="size-3 mr-1" /> New branch
+        </Button>
+      </div>
+
+      {showCreate && (
+        <div className="flex items-center gap-2 rounded-md border border-border p-3">
+          <Input className="h-8 text-[13px] flex-1" placeholder="Branch name" value={newBranchName} onChange={(e) => setNewBranchName(e.target.value)} />
+          <Input className="h-8 w-36 text-[12px]" placeholder="Source (default: HEAD)" value={newBranchSource} onChange={(e) => setNewBranchSource(e.target.value)} />
+          <Button className="h-8 px-3 text-[12px]" disabled={!newBranchName.trim() || createBranch.isPending} onClick={() => createBranch.mutate()}>Create</Button>
+          <Button className="h-8 px-3 text-[12px]" onClick={() => setShowCreate(false)} variant="outline">Cancel</Button>
+        </div>
+      )}
+
+      <div className="rounded-md border border-border overflow-hidden">
+        {isLoading ? (
+          <div className="px-4 py-2">{Array.from({ length: 3 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}</div>
+        ) : filtered.length > 0 ? (
+          <div>
+            {defaultBranches.map((b) => <BranchRow key={b.name} branch={b} isDefault onDelete={deleteBranch} onRename={renameBranch} renaming={renaming} setRenaming={setRenaming} renameValue={renameValue} setRenameValue={setRenameValue} />)}
+            {otherBranches.length > 0 && defaultBranches.length > 0 && (
+              <div className="border-b border-border bg-muted/30 px-3 py-1">
+                <span className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground">Other branches</span>
+              </div>
+            )}
+            {otherBranches.map((b) => <BranchRow key={b.name} branch={b} onDelete={deleteBranch} onRename={renameBranch} renaming={renaming} setRenaming={setRenaming} renameValue={renameValue} setRenameValue={setRenameValue} />)}
+          </div>
+        ) : (
+          <div className="py-12 text-center">
+            <GitBranch className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-3 text-[13px] text-muted-foreground">No branches yet</p>
+          </div>
+        )}
+      </div>
+
+      {/* Branch comparison */}
+      <BranchComparison projectName={projectName} repoName={repoName} branches={branches} />
+    </div>
+  );
+}
+
+function BranchComparison({ projectName, repoName, branches }: { projectName: string; repoName: string; branches: { name: string }[] }) {
+  const [oldBranch, setOldBranch] = useState("");
+  const [newBranch, setNewBranch] = useState("");
+
+  const { data: diffResult } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branch-diff", oldBranch, newBranch],
+    queryFn: async () => {
+      const res = await client.gitDiffBranches(projectName, repoName, { old_branch: oldBranch, new_branch: newBranch });
+      return res.data;
+    },
+    enabled: Boolean(oldBranch && newBranch && oldBranch !== newBranch),
+    retry: false,
+  });
+
+  return (
+    <div className="rounded-md border border-border overflow-hidden">
+      <div className="bg-muted/50 px-3 py-2 border-b border-border">
+        <span className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground">Compare branches</span>
+      </div>
+      <div className="p-3 space-y-3">
+        <div className="flex items-center gap-2">
+          <select className="h-8 flex-1 rounded-sm border border-border bg-card px-2 text-[12px] font-mono text-foreground" value={oldBranch} onChange={(e) => setOldBranch(e.target.value)}>
+            <option value="">Select old branch...</option>
+            {branches.map((b) => <option key={b.name} value={b.name}>{b.name}</option>)}
+          </select>
+          <span className="text-muted-foreground text-[11px]">→</span>
+          <select className="h-8 flex-1 rounded-sm border border-border bg-card px-2 text-[12px] font-mono text-foreground" value={newBranch} onChange={(e) => setNewBranch(e.target.value)}>
+            <option value="">Select new branch...</option>
+            {branches.map((b) => <option key={b.name} value={b.name}>{b.name}</option>)}
+          </select>
+        </div>
+        {diffResult?.stats && (
+          <div className="flex items-center gap-3 text-[12px] font-mono text-muted-foreground">
+            <span>{diffResult.stats.files_changed} files</span>
+            <span className="text-green-600">+{diffResult.stats.insertions}</span>
+            <span className="text-red-600">-{diffResult.stats.deletions}</span>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function BranchRow({ branch, isDefault, onDelete, onRename, renaming, setRenaming, renameValue, setRenameValue }: {
+  branch: { name: string; oid: string; is_current?: boolean; is_head?: boolean };
+  isDefault?: boolean;
+  onDelete: any;
+  onRename: any;
+  renaming: string | null;
+  setRenaming: any;
+  renameValue: string;
+  setRenameValue: any;
+}) {
+  const isEditing = renaming === branch.name;
+  return (
+    <div className="flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0 transition-colors hover:bg-muted/40">
+      <GitBranch className={cn("size-4 shrink-0", isDefault ? "text-primary" : "text-muted-foreground")} />
+      {isEditing ? (
+        <div className="flex items-center gap-2 flex-1">
+          <Input className="h-7 text-[13px] flex-1" value={renameValue} onChange={(e) => setRenameValue(e.target.value)} autoFocus />
+          <Button className="h-7 px-2 text-[11px]" disabled={!renameValue.trim()} onClick={() => onRename.mutate({ oldName: branch.name, newName: renameValue.trim() })}>Save</Button>
+          <Button className="h-7 px-2 text-[11px]" onClick={() => setRenaming(null)} variant="outline">Cancel</Button>
+        </div>
+      ) : (
+        <>
+          <span className="font-heading text-[13px] font-semibold text-foreground">{branch.name}</span>
+          {isDefault && <span className="rounded-sm border border-primary/30 bg-primary/5 px-1.5 py-0.5 font-mono text-[10px] text-primary leading-none">Default</span>}
+          <div className="ml-auto flex items-center gap-1">
+            {branch.is_head && <span className="font-mono text-[10px] text-muted-foreground">HEAD</span>}
+            <code className="font-mono text-[10px] text-muted-foreground/60">{branch.oid.slice(0, 7)}</code>
+            {!isDefault && (
+              <Button className="size-7 text-muted-foreground hover:text-foreground" onClick={() => { setRenaming(branch.name); setRenameValue(branch.name); }} size="icon" variant="ghost">
+                <Pencil className="size-3" />
+              </Button>
+            )}
+            {!isDefault && (
+              <Button className="size-7 text-destructive hover:text-destructive" onClick={() => { if (confirm(`Delete branch "${branch.name}"?`)) onDelete.mutate(branch.name); }} size="icon" variant="ghost">
+                <Trash2 className="size-3.5" />
+              </Button>
+            )}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/code.tsx b/src/page/workspace/repo/code.tsx
new file mode 100644
index 0000000..1c1db72
--- /dev/null
+++ b/src/page/workspace/repo/code.tsx
@@ -0,0 +1,604 @@
+import { useState, useEffect, useCallback } from "react";
+import { useParams, useSearchParams } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { client, type TreeEntryDto, type TreeKindDto } from "@/client";
+import {
+  Copy,
+  Check,
+  GitBranch,
+  GitCommitHorizontal,
+  FileText,
+  Folder,
+  Package,
+  ChevronRight,
+  ChevronDown,
+  Star,
+  FolderOpen,
+  AlertTriangle,
+  Download,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+
+const LANGUAGE_COLORS: Record<string, string> = {
+  Rust: "#dea584",
+  TypeScript: "#3178c6",
+  JavaScript: "#f1e05a",
+  Python: "#3572A5",
+  Go: "#00ADD8",
+  Java: "#b07219",
+  "C++": "#f34b7d",
+  C: "#555555",
+  HTML: "#e34c26",
+  CSS: "#563d7c",
+  Shell: "#89e051",
+  Markdown: "#083fa1",
+  Vue: "#41b883",
+  Ruby: "#701516",
+  Swift: "#F05138",
+  Kotlin: "#A97BFF",
+  Dart: "#00B4AB",
+  Scala: "#c22d40",
+  R: "#198CE7",
+  Zig: "#ec915c",
+  Nix: "#7e7eff",
+  CMake: "#DA3434",
+  Dockerfile: "#384d54",
+};
+
+function formatTimeAgo(timeSecs: number) {
+  const now = Math.floor(Date.now() / 1000);
+  const diff = now - timeSecs;
+  if (diff < 60) return "just now";
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  if (diff < 2592000) return `${Math.floor(diff / 86400)}d ago`;
+  return new Date(timeSecs * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+function decodeBase64(base64: string): string {
+  try {
+    return atob(base64);
+  } catch {
+    return "";
+  }
+}
+
+function formatTimeAgoEntry(ts: string) {
+  const d = new Date(Number(ts) * 1000);
+  const now = Date.now();
+  const diff = now - d.getTime();
+  if (diff < 3600000) return `${Math.floor(diff / 60000)}m`;
+  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h`;
+  if (diff < 2592000000) return `${Math.floor(diff / 86400000)}d`;
+  return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+function FileIcon({ kind }: { kind: TreeKindDto }) {
+  if (kind === "tree") return <Folder className="size-4 text-muted-foreground shrink-0" />;
+  if (kind === "lfs_pointer") return <Package className="size-4 text-muted-foreground shrink-0" />;
+  return <FileText className="size-4 text-muted-foreground shrink-0" />;
+}
+
+function AuthorAvatar({ author }: { author: { name: string } }) {
+  return (
+    <span
+      className={cn(
+        "grid size-5 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white",
+        workspaceColor(author.name),
+      )}
+    >
+      {workspaceInitial(author.name)}
+    </span>
+  );
+}
+
+export default function CodeTab() {
+  const { projectName = "", repoName = "" } = useParams();
+
+  // Get default branch
+  const { data: repoData } = useQuery({
+    queryKey: ["repo", projectName, repoName],
+    queryFn: async () => {
+      const res = await client.gitGetRepo(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const defaultBranch = repoData?.default_branch ?? "main";
+  const [selectedBranch, setSelectedBranch] = useState(defaultBranch);
+  const [branchOpen, setBranchOpen] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const [cloneMethod, setCloneMethod] = useState<"https" | "ssh">("https");
+  const [treeStack, setTreeStack] = useState<{ oid: string; name: string }[]>([]);
+  const [viewingFile, setViewingFile] = useState<{ oid: string; name: string; isBinary: boolean } | null>(null);
+  const [showBlame, setShowBlame] = useState(false);
+
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const cloneUrl = cloneMethod === "https"
+    ? `${origin}/${projectName}/${repoName}.git`
+    : `git@${origin.replace(/^https?:\/\//, "")}:${projectName}/${repoName}.git`;
+
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(cloneUrl);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch { /* noop */ }
+  };
+
+  // Branch list
+  const { data: branchList } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branches"],
+    queryFn: async () => {
+      const res = await client.gitListBranches(projectName, repoName);
+      return res.data.branches;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  // Branch info → commit OID
+  const { data: branchInfo } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branch-info", selectedBranch],
+    queryFn: async () => {
+      const res = await (client as any).gitBranchInfo(projectName, repoName, selectedBranch);
+      return res.data.branch;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  // Commit info → tree OID
+  const { data: commitInfo } = useQuery({
+    queryKey: ["repo", projectName, repoName, "commit-info", branchInfo?.oid],
+    queryFn: async () => {
+      const res = await (client as any).gitCommitInfo(projectName, repoName, branchInfo!.oid);
+      return res.data.commit;
+    },
+    enabled: Boolean(branchInfo?.oid),
+    retry: false,
+  });
+
+  const rootTreeOid = commitInfo?.tree_id ?? null;
+
+  // Reset navigation when branch changes
+   
+  useEffect(() => {
+    if (rootTreeOid) {
+      setTreeStack([{ oid: rootTreeOid, name: repoName }]);
+      setViewingFile(null);
+      setSearchParams({}, { replace: true });
+    } else {
+      setTreeStack([]);
+      setViewingFile(null);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rootTreeOid, repoName]);
+
+  // URL → tree stack sync for browser back/forward
+  const urlDirPath = searchParams.get("path") ?? "";
+   
+  useEffect(() => {
+    const curPath = treeStack.slice(1).map((s) => s.name).join("/");
+    if (!rootTreeOid || urlDirPath === curPath) return;
+    setViewingFile(null);
+    if (!urlDirPath) {
+      setTreeStack([{ oid: rootTreeOid, name: repoName }]);
+    } else {
+      (async () => {
+        const segments = urlDirPath.split("/");
+        const stack = [{ oid: rootTreeOid, name: repoName }];
+        let curTree = rootTreeOid;
+        for (const seg of segments) {
+          try {
+            const sub = await (client as any).gitTreeEntryByPath(projectName, repoName, curTree, { path: seg });
+            if (sub.data.entry && sub.data.entry.kind === "tree") {
+              stack.push({ oid: sub.data.entry.oid, name: seg });
+              curTree = sub.data.entry.oid;
+            } else break;
+          } catch { break; }
+        }
+        if (stack.length > 1) setTreeStack(stack);
+      })();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [urlDirPath, rootTreeOid]);
+
+  // Current tree OID from stack top
+  const currentTreeOid = treeStack.length > 0 ? treeStack[treeStack.length - 1].oid : null;
+  // Current directory path (skip root: repoName)
+  const currentDirPath = treeStack.slice(1).map((s) => s.name).join("/");
+
+  // Fast tree entries (no last commit info)
+  const { data: fastEntries } = useQuery({
+    queryKey: ["repo", projectName, repoName, "tree", currentTreeOid, currentDirPath, "fast"],
+    queryFn: async () => {
+      const res = await (client as any).gitTreeEntries(projectName, repoName, currentTreeOid!, { path: currentDirPath || undefined });
+      return res.data.entries;
+    },
+    enabled: Boolean(currentTreeOid),
+    retry: false,
+  });
+
+  // Full tree entries (with last commit info, may be async)
+  const { data: fullEntries } = useQuery({
+    queryKey: ["repo", projectName, repoName, "tree", currentTreeOid, currentDirPath, "full"],
+    queryFn: async () => {
+      const res = await (client as any).gitTreeEntries(projectName, repoName, currentTreeOid!, { path: currentDirPath || undefined, last: true } as any);
+      return res.data.entries;
+    },
+    enabled: Boolean(currentTreeOid),
+    retry: false,
+  });
+
+  const displayEntries = (fullEntries ?? fastEntries) ?? [];
+
+  // Latest commit for selected branch
+  const { data: latestCommit } = useQuery({
+    queryKey: ["repo", projectName, repoName, "latest-commit", selectedBranch],
+    queryFn: async () => {
+      const res = await client.gitCommitHistory(projectName, repoName, { branch: selectedBranch, limit: 1 });
+      return res.data.commits[0] ?? null;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  // Blob content for viewed file
+  const { data: blobData, isLoading: blobLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "blob", viewingFile?.oid],
+    queryFn: async () => {
+      const res = await (client as any).gitBlobInfo(projectName, repoName, viewingFile!.oid, { path: viewingFile!.name } as any);
+      return res.data;
+    },
+    enabled: Boolean(viewingFile) && !viewingFile?.isBinary,
+    retry: false,
+  });
+
+  // Blame lines
+  const { data: blameLines } = useQuery({
+    queryKey: ["repo", projectName, repoName, "blame", viewingFile?.name],
+    queryFn: async () => {
+      const res: any = await client.gitBlameFile(projectName, repoName, { path: viewingFile!.name, start_line: 1, end_line: 999999 });
+      return res.data?.lines as { commit_oid?: string | null; content: string; line_no: number }[] | undefined;
+    },
+    enabled: Boolean(showBlame && viewingFile && !viewingFile?.isBinary),
+    retry: false,
+  });
+
+  // Commit info for blame (unique OIDs)
+  const blameOids = blameLines ? [...new Set(blameLines.map((l) => l.commit_oid).filter(Boolean))] : [];
+  const { data: blameCommits } = useQuery({
+    queryKey: ["repo", projectName, repoName, "blame-commits", ...blameOids.slice(0, 10)],
+    queryFn: async () => {
+      const results: Record<string, string> = {};
+      for (const oid of blameOids.slice(0, 10)) {
+        if (oid) {
+          try {
+            const res = await (client as any).gitCommitInfo(projectName, repoName, oid);
+            results[oid] = res.data.commit?.author?.name ?? "?";
+          } catch { results[oid] = "?"; }
+        }
+      }
+      return results;
+    },
+    enabled: blameOids.length > 0,
+    retry: false,
+  });
+
+  // Language stats
+  const { data: languages = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "languages"],
+    queryFn: async () => {
+      const res = await client.gitGetLanguages(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const handleBranchSelect = useCallback((name: string) => {
+    setSelectedBranch(name);
+    setBranchOpen(false);
+  }, []);
+
+  const handleTreeNavigate = useCallback((entry: TreeEntryDto) => {
+    setViewingFile(null);
+    const path = [...treeStack.slice(1).map((s) => s.name), entry.name].join("/");
+    setTreeStack((prev) => [...prev, { oid: entry.oid, name: entry.name }]);
+    setSearchParams(path ? { path } : {}, { replace: true });
+  }, [treeStack, setSearchParams]);
+
+  const handleFileView = useCallback((entry: TreeEntryDto) => {
+    setViewingFile({ oid: entry.oid, name: entry.name, isBinary: entry.is_binary });
+  }, []);
+
+  const handleBreadcrumbClick = useCallback((index: number) => {
+    setViewingFile(null);
+    const path = treeStack.slice(1, index + 1).map((s) => s.name).join("/");
+    setTreeStack((prev) => prev.slice(0, index + 1));
+    setSearchParams(path ? { path } : {}, { replace: true });
+  }, [treeStack, setSearchParams]);
+
+  const entries = displayEntries;
+
+  // Stable skeleton widths — computed once at module level
+  const [skeletonWidths] = useState(() => Array.from({ length: 12 }, () => 30 + Math.floor(Math.random() * 60)));
+
+  return (
+    <div className="space-y-4">
+      {/* Top action bar */}
+      <div className="flex items-center gap-3 flex-wrap">
+        {/* Branch dropdown */}
+        <div className="relative">
+          <button
+            className="flex items-center gap-1.5 rounded-sm border border-border px-3 py-1.5 text-[13px] font-medium text-foreground bg-card transition-colors hover:bg-muted/40"
+            onClick={() => setBranchOpen(!branchOpen)}
+          >
+            <GitBranch className="size-3.5 text-muted-foreground" />
+            <span className="font-heading">{selectedBranch}</span>
+            <ChevronDown className={cn("size-3 text-muted-foreground transition-transform", branchOpen && "rotate-180")} />
+          </button>
+          {branchOpen && (
+            <>
+              <div className="fixed inset-0 z-40" onClick={() => setBranchOpen(false)} />
+              <div className="absolute top-full left-0 mt-1 z-50 w-56 rounded-md border border-border bg-card shadow-lg overflow-hidden">
+                <div className="px-3 py-2 border-b border-border bg-muted/50">
+                  <span className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground">Switch branch</span>
+                </div>
+                <div className="max-h-56 overflow-y-auto">
+                  {branchList && branchList.length > 0 ? branchList.map((b) => (
+                    <button
+                      className={cn(
+                        "flex items-center gap-2 px-3 py-2 text-[13px] w-full transition-colors",
+                        b.name === selectedBranch ? "bg-primary/5 text-foreground" : "text-foreground hover:bg-muted/40",
+                      )}
+                      key={b.name}
+                      onClick={() => handleBranchSelect(b.name)}
+                    >
+                      <GitBranch className={cn("size-3", b.name === defaultBranch ? "text-primary" : "text-muted-foreground")} />
+                      <span className="font-heading font-medium">{b.name}</span>
+                      {b.name === defaultBranch && <Star className="size-2.5 text-primary ml-auto" />}
+                    </button>
+                  )) : (
+                    <div className="px-3 py-4 text-center text-[12px] text-muted-foreground">No branches found</div>
+                  )}
+                </div>
+              </div>
+            </>
+          )}
+        </div>
+
+        {/* Clone section */}
+        <div className="ml-auto flex items-center gap-1 rounded-sm border border-border overflow-hidden">
+          <div className="flex items-center">
+            <button
+              className={cn("px-2 py-1 text-[11px] font-mono transition-colors", cloneMethod === "https" ? "text-foreground bg-muted/50" : "text-muted-foreground hover:text-foreground")}
+              onClick={() => setCloneMethod("https")}
+            >
+              HTTPS
+            </button>
+            <button
+              className={cn("px-2 py-1 text-[11px] font-mono transition-colors", cloneMethod === "ssh" ? "text-foreground bg-muted/50" : "text-muted-foreground hover:text-foreground")}
+              onClick={() => setCloneMethod("ssh")}
+            >
+              SSH
+            </button>
+          </div>
+          <code className="flex-1 px-2 py-1 font-mono text-[12px] text-foreground truncate select-all border-l border-border">
+            {cloneUrl}
+          </code>
+          <Button className="size-6 text-muted-foreground" onClick={handleCopy} size="icon" variant="ghost">
+            {copied ? <Check className="size-3" /> : <Copy className="size-3" />}
+          </Button>
+        </div>
+
+        {/* Archive buttons */}
+        <span className="h-5 w-px bg-border" />
+        <div className="flex items-center border border-border rounded-sm overflow-hidden">
+          <a
+            className="flex items-center gap-1 px-2 py-1 text-[11px] font-mono text-muted-foreground hover:text-foreground hover:bg-muted/40 transition-colors"
+            href={`/api/v1/workspace/${projectName}/repos/${repoName}/git/archive/tar`}
+            download
+          >
+            <Download className="size-3" /> TAR
+          </a>
+          <span className="w-px h-4 bg-border" />
+          <a
+            className="flex items-center gap-1 px-2 py-1 text-[11px] font-mono text-muted-foreground hover:text-foreground hover:bg-muted/40 transition-colors"
+            href={`/api/v1/workspace/${projectName}/repos/${repoName}/git/archive/zip`}
+            download
+          >
+            <Download className="size-3" /> ZIP
+          </a>
+        </div>
+      </div>
+
+      {/* Language stats */}
+      {languages.length > 0 && (
+        <div className="flex items-center gap-0.5 h-1.5 rounded-full overflow-hidden bg-muted/30">
+          {languages.map((lang) => (
+            <div
+              className="h-full transition-all"
+              key={lang.language}
+              style={{ width: `${lang.percentage}%`, backgroundColor: LANGUAGE_COLORS[lang.language] ?? "#888" }}
+              title={`${lang.language}: ${lang.percentage.toFixed(1)}%`}
+            />
+          ))}
+        </div>
+      )}
+
+      {/* Latest commit bar */}
+      {latestCommit && (
+        <div className="flex items-center gap-2 rounded-sm border border-border bg-muted/30 px-3 py-2">
+          <GitCommitHorizontal className="size-4 text-muted-foreground shrink-0" />
+          <div className="flex items-center gap-1.5 min-w-0">
+            <AuthorAvatar author={{ name: latestCommit.author?.name ?? "unknown" }} />
+            <span className="font-heading text-[13px] font-semibold text-foreground truncate">{latestCommit.summary}</span>
+          </div>
+          <span className="font-mono text-[11px] text-muted-foreground shrink-0 ml-auto">
+            {latestCommit.author?.time_secs ? formatTimeAgo(latestCommit.author.time_secs) : ""}
+          </span>
+          <code className="font-mono text-[11px] text-muted-foreground/60 shrink-0">{latestCommit.oid.slice(0, 7)}</code>
+        </div>
+      )}
+
+      {/* Content area: file tree or file viewer */}
+      <div className="rounded-md border border-border overflow-hidden">
+        {/* Breadcrumb */}
+        <div className="flex items-center gap-0.5 bg-muted/50 px-3 py-2 border-b border-border overflow-x-auto">
+          {treeStack.map((item, i) => (
+            <button
+              className={cn(
+                "flex items-center gap-0.5 text-[12px] shrink-0 transition-colors hover:text-foreground",
+                i === treeStack.length - 1 ? "text-foreground font-medium" : "text-muted-foreground",
+              )}
+              key={`${item.oid}-${i}`}
+              onClick={() => handleBreadcrumbClick(i)}
+            >
+              {i === 0 ? (
+                <FolderOpen className="size-3.5" />
+              ) : (
+                <span className="text-muted-foreground/40 mx-0.5">/</span>
+              )}
+              <span className="font-mono truncate max-w-[120px]">{item.name}</span>
+            </button>
+          ))}
+          {viewingFile && (
+            <>
+              <ChevronRight className="size-3 text-muted-foreground/40 mx-0.5" />
+              <span className="text-[12px] text-foreground font-medium shrink-0">{viewingFile.name}</span>
+              <button className="ml-3 text-[11px] text-muted-foreground hover:text-foreground shrink-0" onClick={() => setShowBlame(!showBlame)}>
+                {showBlame ? "code" : "blame"}
+              </button>
+              <button
+                className="ml-2 text-[11px] text-muted-foreground hover:text-foreground shrink-0"
+                onClick={() => setViewingFile(null)}
+              >
+                &times; close
+              </button>
+            </>
+          )}
+        </div>
+
+        {/* File viewer */}
+        {viewingFile ? (
+          viewingFile.isBinary ? (
+            <div className="py-12 text-center">
+              <AlertTriangle className="mx-auto size-5 text-muted-foreground/20" />
+              <p className="mt-2 text-[13px] text-muted-foreground">Binary file</p>
+              <p className="text-[11px] text-muted-foreground/60">This file cannot be displayed in the browser.</p>
+            </div>
+          ) : blobLoading ? (
+            <div className="px-4 py-8 space-y-2">{skeletonWidths.map((w, i) => <div className="h-4 animate-pulse rounded bg-muted/50" key={i} style={{ width: `${w}%` }} />)}</div>
+          ) : blobData ? (
+            <div className="overflow-auto max-h-[600px]">
+              {showBlame && blameLines ? (
+                <table className="w-full font-mono text-[12px] leading-relaxed">
+                  <tbody>
+                    {blameLines.map((line, i) => (
+                      <tr className="hover:bg-muted/20" key={i}>
+                        <td className="w-16 min-w-[64px] text-right px-1 text-muted-foreground/40 select-none border-r border-border">
+                          {line.line_no}
+                        </td>
+                        {line.commit_oid && (
+                          <td className="w-14 min-w-[56px] text-right px-1 text-muted-foreground/50 select-all truncate" title={blameCommits?.[line.commit_oid] ?? ""}>
+                            <span className="text-[10px]">{blameCommits?.[line.commit_oid] ?? line.commit_oid.slice(0, 6)}</span>
+                          </td>
+                        )}
+                        <td className="px-2 whitespace-pre text-foreground">{line.content}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              ) : (
+                <pre className="px-4 py-3 font-mono text-[12px] text-foreground leading-relaxed whitespace-pre">{decodeBase64((blobData as any).blob)}</pre>
+              )}
+            </div>
+          ) : (
+            <div className="py-12 text-center">
+              <p className="text-[13px] text-muted-foreground">Could not load file content</p>
+            </div>
+          )
+        ) : entries.length > 0 ? (
+          /* File tree */
+          <div>
+            {entries
+              .slice()
+              .sort((a: any, b: any) => {
+                if (a.kind !== b.kind) return a.kind === "tree" ? -1 : 1;
+                return a.name.localeCompare(b.name);
+              })
+              .map((entry: any) => (
+                <div
+                  className="flex items-center gap-3 border-b border-border px-3 py-2 last:border-b-0 transition-colors hover:bg-muted/40 cursor-pointer"
+                  key={entry.name}
+                  onClick={() => {
+                    if (entry.kind === "tree") handleTreeNavigate(entry);
+                    else handleFileView(entry);
+                  }}
+                >
+                  <FileIcon kind={entry.kind} />
+                  <span className={cn(
+                    "text-[13px] truncate",
+                    entry.kind === "tree" ? "font-heading font-semibold text-foreground" : "text-foreground",
+                  )}>
+                    {entry.name}
+                  </span>
+                  {entry.is_lfs && (
+                    <span className="rounded-sm border border-border px-1 py-0.5 font-mono text-[9px] text-muted-foreground leading-none shrink-0">
+                      LFS
+                    </span>
+                  )}
+                  <div className="ml-auto flex items-center gap-3 min-w-0">
+                    {entry.last_commit_message && (
+                      <span className="font-mono text-[11px] text-muted-foreground/60 truncate max-w-[280px] hidden sm:block">{entry.last_commit_message}</span>
+                    )}
+                    {entry.last_commit_author_name && (
+                      <span className="font-mono text-[11px] text-muted-foreground shrink-0">{entry.last_commit_author_name}</span>
+                    )}
+                    {entry.last_commit_time && (
+                      <span className="font-mono text-[10px] text-muted-foreground/40 shrink-0">{formatTimeAgoEntry(entry.last_commit_time)}</span>
+                    )}
+                  </div>
+                </div>
+              ))}
+          </div>
+        ) : currentTreeOid ? (
+          <div className="py-8 text-center">
+            <Folder className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-2 text-[13px] text-muted-foreground">Empty directory</p>
+          </div>
+        ) : (
+          <div className="py-12 text-center">
+            <GitCommitHorizontal className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-2 text-[13px] text-muted-foreground">No content</p>
+            <p className="text-[11px] text-muted-foreground/60">
+              Push a commit to get started
+            </p>
+          </div>
+        )}
+      </div>
+
+      {/* Language legend */}
+      {languages.length > 1 && (
+        <div className="flex items-center gap-3 flex-wrap text-[11px] text-muted-foreground">
+          {languages.map((lang) => (
+            <span className="flex items-center gap-1" key={lang.language}>
+              <span className="inline-block size-2 rounded-sm" style={{ backgroundColor: LANGUAGE_COLORS[lang.language] ?? "#888" }} />
+              {lang.language}
+              <span className="font-mono text-[10px]">{lang.percentage.toFixed(1)}%</span>
+            </span>
+          ))}
+        </div>
+      )}
+
+      </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/commit-detail.tsx b/src/page/workspace/repo/commit-detail.tsx
new file mode 100644
index 0000000..aea35ac
--- /dev/null
+++ b/src/page/workspace/repo/commit-detail.tsx
@@ -0,0 +1,188 @@
+import { useState } from "react";
+import { Link, useParams } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { GitCommitHorizontal, Plus, Minus, FileCode, ArrowLeft } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+
+function formatTimeAgo(timeSecs: number) {
+  const now = Math.floor(Date.now() / 1000);
+  const diff = now - timeSecs;
+  if (diff < 60) return "just now";
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  if (diff < 2592000) return `${Math.floor(diff / 86400)}d ago`;
+  return new Date(timeSecs * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
+
+function AuthorAvatar({ author }: { author: { name: string } }) {
+  return (
+    <span className={cn("grid size-6 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white", workspaceColor(author.name))}>
+      {workspaceInitial(author.name)}
+    </span>
+  );
+}
+
+export default function CommitDetailPage() {
+  const { projectName = "", repoName = "", oid = "" } = useParams();
+  const [selectedFileIndex, setSelectedFileIndex] = useState(0);
+
+  const { data: commit, isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "commit-info", oid],
+    queryFn: async () => {
+      const res = await (client as any).gitCommitInfo(projectName, repoName, oid);
+      return res.data.commit;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName) && Boolean(oid),
+    retry: false,
+  });
+
+  const parentOid = commit?.parent_ids?.[0];
+
+  const { data: diffData, error: diffError } = useQuery({
+    queryKey: ["repo", projectName, repoName, "diff", oid],
+    queryFn: async () => {
+      if (!parentOid) return null;
+      const res = await client.gitDiff(projectName, repoName, { old_oid: parentOid, new_oid: oid });
+      return res.data;
+    },
+    enabled: Boolean(parentOid),
+    retry: false,
+  });
+
+  if (isLoading) {
+    return (
+      <div className="px-8 py-10 space-y-4">
+        <div className="h-7 animate-pulse rounded bg-muted/50 w-64" />
+        <div className="h-20 animate-pulse rounded bg-muted/50" />
+      </div>
+    );
+  }
+
+  if (!commit) {
+    return (
+      <div className="px-8 py-10 text-center">
+        <GitCommitHorizontal className="mx-auto size-5 text-muted-foreground/20" />
+        <p className="mt-3 text-[13px] text-muted-foreground">Commit not found</p>
+      </div>
+    );
+  }
+
+  const extras = commit.parent_ids.length > 1 ? `(merge commit: ${commit.parent_ids.length} parents)` : "";
+  const deltas = (diffData as any)?.deltas ?? [];
+  const selectedDelta = deltas[selectedFileIndex] ?? null;
+
+  return (
+    <div className="px-8 py-10">
+      {/* Back link */}
+      <Link className="inline-flex items-center gap-1 text-[12px] text-muted-foreground hover:text-foreground transition-colors mb-4" to={`/${projectName}/repo/${repoName}`}>
+        <ArrowLeft className="size-3.5" />
+        Back to repository
+      </Link>
+
+      {/* Commit header */}
+      <div className="flex items-start gap-3">
+        <AuthorAvatar author={{ name: commit.author?.name ?? "unknown" }} />
+        <div className="min-w-0 flex-1">
+          <h1 className="font-heading text-[15px] font-bold text-foreground break-words">{commit.summary}</h1>
+          {commit.message !== commit.summary && (
+            <pre className="mt-1 text-[13px] text-muted-foreground whitespace-pre-wrap font-sans">{commit.message.slice(commit.summary.length).trim()}</pre>
+          )}
+          <div className="mt-1.5 flex items-center gap-2 font-mono text-[12px] text-muted-foreground flex-wrap">
+            <span className="font-medium text-foreground">{commit.author?.name}</span>
+            <span>authored {commit.author?.time_secs ? formatTimeAgo(commit.author.time_secs) : ""}</span>
+            {commit.committer?.name !== commit.author?.name && <span>(committed by {commit.committer?.name})</span>}
+            <code className="text-muted-foreground/60">{commit.oid.slice(0, 7)}</code>
+            {extras && <span className="text-muted-foreground/60">{extras}</span>}
+          </div>
+        </div>
+      </div>
+
+      {/* Diff stats */}
+      {(diffData as any)?.stats && (
+        <div className="mt-4 flex items-center gap-4 text-[12px]">
+          <span className="font-mono text-muted-foreground">{ (diffData as any).stats.files_changed} files</span>
+          <span className="flex items-center gap-1 text-green-600 font-mono"><Plus className="size-3" />{ (diffData as any).stats.insertions}</span>
+          <span className="flex items-center gap-1 text-red-600 font-mono"><Minus className="size-3" />{ (diffData as any).stats.deletions}</span>
+        </div>
+      )}
+
+      {/* Two-column layout */}
+      {deltas.length > 0 ? (
+        <div className="mt-4 grid grid-cols-[240px_1fr] gap-0 rounded-md border border-border overflow-hidden">
+          {/* Left: file list */}
+          <div className="border-r border-border bg-muted/20 overflow-y-auto max-h-[calc(100vh-280px)]">
+            <div className="px-3 py-2 border-b border-border bg-muted/40">
+              <span className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground">Files changed</span>
+            </div>
+            {deltas.map((delta: any, i: number) => {
+              const path = delta.new_file?.path ?? delta.old_file?.path ?? "unknown";
+              return (
+                <button
+                  className={cn(
+                    "flex items-center gap-2 w-full px-3 py-2 text-left transition-colors border-b border-border last:border-b-0",
+                    i === selectedFileIndex ? "bg-primary/5 text-foreground" : "text-muted-foreground hover:bg-muted/40 hover:text-foreground",
+                  )}
+                  key={i}
+                  onClick={() => setSelectedFileIndex(i)}
+                >
+                  <FileCode className="size-3.5 shrink-0" />
+                  <span className="font-mono text-[12px] truncate">{path}</span>
+                  {delta.new_file?.is_binary && <span className="font-mono text-[9px] text-muted-foreground ml-auto shrink-0">bin</span>}
+                </button>
+              );
+            })}
+          </div>
+
+          {/* Right: diff content */}
+          <div className="overflow-y-auto max-h-[calc(100vh-280px)]">
+            {selectedDelta && (
+              <div>
+                <div className="flex items-center gap-2 bg-muted/40 px-4 py-2 border-b border-border sticky top-0">
+                  <FileCode className="size-4 text-muted-foreground shrink-0" />
+                  <span className="font-heading text-[13px] font-medium text-foreground truncate">
+                    {selectedDelta.new_file?.path ?? selectedDelta.old_file?.path ?? "unknown"}
+                  </span>
+                  {selectedDelta.old_file?.is_binary && <span className="font-mono text-[10px] text-muted-foreground ml-auto">Binary file</span>}
+                </div>
+                {!selectedDelta.old_file?.is_binary && selectedDelta.lines.length > 0 ? (
+                  <table className="w-full font-mono text-[12px] leading-relaxed">
+                    <tbody>
+                      {selectedDelta.lines.map((line: any, j: number) => (
+                        <tr className={cn(line.origin === "+" && "bg-green-950/20", line.origin === "-" && "bg-red-950/20")} key={j}>
+                          <td className="w-12 min-w-[48px] text-right px-2 text-muted-foreground/40 select-none border-r border-border">{line.old_lineno ?? ""}</td>
+                          <td className="w-12 min-w-[48px] text-right px-2 text-muted-foreground/40 select-none border-r border-border">{line.new_lineno ?? ""}</td>
+                          <td className="w-4 min-w-[16px] text-center text-muted-foreground/50 select-none">{line.origin}</td>
+                          <td className={cn("px-3 whitespace-pre", line.origin === "+" ? "text-green-400" : line.origin === "-" ? "text-red-400" : "text-foreground")}>{line.content}</td>
+                        </tr>
+                      ))}
+                    </tbody>
+                  </table>
+                ) : selectedDelta.old_file?.is_binary ? null : (
+                  <div className="py-6 text-center text-[12px] text-muted-foreground">No diff lines</div>
+                )}
+              </div>
+            )}
+          </div>
+        </div>
+      ) : diffData ? (
+        <div className="mt-6 py-8 text-center rounded-md border border-border">
+          <p className="text-[13px] text-muted-foreground">No file changes</p>
+        </div>
+      ) : parentOid ? (
+        <div className="mt-6 py-8 text-center rounded-md border border-border">
+          <p className="text-[13px] text-muted-foreground">
+            {diffError ? `Diff error: ${(diffError as any)?.message || 'unknown'}` : 'Loading diff…'}
+          </p>
+        </div>
+      ) : (
+        <div className="mt-6 py-8 text-center rounded-md border border-border">
+          <GitCommitHorizontal className="mx-auto size-5 text-muted-foreground/20" />
+          <p className="mt-2 text-[13px] text-muted-foreground">Initial commit</p>
+          <p className="text-[11px] text-muted-foreground/60">This is the first commit in the repository.</p>
+        </div>
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/commits.tsx b/src/page/workspace/repo/commits.tsx
new file mode 100644
index 0000000..6f5006d
--- /dev/null
+++ b/src/page/workspace/repo/commits.tsx
@@ -0,0 +1,140 @@
+import { useState } from "react";
+import { Link, useParams, useSearchParams } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { GitCommitHorizontal, Search } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import PaginationBar from "./pagination";
+
+function formatTimeAgo(timeSecs: number) {
+  const now = Math.floor(Date.now() / 1000);
+  const diff = now - timeSecs;
+  if (diff < 60) return "just now";
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  if (diff < 2592000) return `${Math.floor(diff / 86400)}d ago`;
+  return new Date(timeSecs * 1000).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+function AuthorAvatar({ author }: { author: { name: string } }) {
+  return (
+    <span
+      className={cn(
+        "grid size-5 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white",
+        workspaceColor(author.name),
+      )}
+    >
+      {workspaceInitial(author.name)}
+    </span>
+  );
+}
+
+const LIMIT = 30;
+
+export default function CommitsTab() {
+  const { projectName = "", repoName = "" } = useParams();
+  const [commitsSearchParams, setCommitsSearchParams] = useSearchParams();
+  const offset = Number(commitsSearchParams.get("offset") ?? "0");
+  const setOffset = (n: number) => {
+    const next = new URLSearchParams(commitsSearchParams);
+    if (n <= 0) next.delete("offset"); else next.set("offset", String(n));
+    setCommitsSearchParams(next, { replace: true });
+  };
+
+  const { data: repoData } = useQuery({
+    queryKey: ["repo", projectName, repoName],
+    queryFn: async () => {
+      const res = await client.gitGetRepo(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const defaultBranch = repoData?.default_branch ?? "main";
+  const [search, setSearch] = useState("");
+  const [selectedBranch, setSelectedBranch] = useState(defaultBranch);
+
+  const { data: commits = [], isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "commits", selectedBranch, offset],
+    queryFn: async () => {
+      const res = await client.gitCommitHistory(projectName, repoName, { branch: selectedBranch, skip: offset, limit: LIMIT });
+      return res.data.commits;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const { data: branches = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branches"],
+    queryFn: async () => {
+      const res = await client.gitListBranches(projectName, repoName);
+      return res.data.branches;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const filtered = search
+    ? commits.filter((c) => c.message.toLowerCase().includes(search.toLowerCase()) || c.oid.startsWith(search))
+    : commits;
+
+  return (
+    <div>
+      <div className="flex items-center gap-3 mb-4">
+        <select
+          className="h-8 rounded-sm border border-border bg-card px-2 text-[12px] font-mono text-foreground"
+          value={selectedBranch}
+          onChange={(e) => { setSelectedBranch(e.target.value); setOffset(0); }}
+        >
+          {branches.map((b) => (
+            <option key={b.name} value={b.name}>{b.name}</option>
+          ))}
+        </select>
+        <div className="ml-auto relative">
+          <Search className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+          <Input className="h-7 w-52 rounded-sm border-border bg-card pl-7 text-[12px]" placeholder="Search commits..." value={search} onChange={(e) => setSearch(e.target.value)} />
+        </div>
+      </div>
+
+      <div className="rounded-md border border-border overflow-hidden">
+        {isLoading ? (
+          <div className="px-4 py-2">
+            {Array.from({ length: 8 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}
+          </div>
+        ) : filtered.length > 0 ? (
+          <>
+          <div>
+            {filtered.map((commit) => (
+              <Link
+                className="flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0 transition-colors hover:bg-muted/40"
+                key={commit.oid}
+                to={`/${projectName}/repo/${repoName}/commits/${commit.oid}`}
+              >
+                <GitCommitHorizontal className="size-4 text-muted-foreground shrink-0" />
+                <div className="min-w-0 flex-1">
+                  <span className="font-heading text-[13px] font-semibold text-foreground truncate block leading-tight">{commit.summary}</span>
+                </div>
+                <div className="flex items-center gap-2 shrink-0">
+                  <AuthorAvatar author={{ name: commit.author?.name ?? "unknown" }} />
+                  <span className="font-mono text-[11px] text-muted-foreground">{commit.author?.name}</span>
+                  <span className="font-mono text-[11px] text-muted-foreground">{commit.author?.time_secs ? formatTimeAgo(commit.author.time_secs) : ""}</span>
+                  <code className="font-mono text-[11px] text-muted-foreground/60">{commit.oid.slice(0, 7)}</code>
+                </div>
+              </Link>
+            ))}
+          </div>
+          <PaginationBar offset={offset} limit={LIMIT} hasMore={commits.length >= LIMIT} onPrev={() => setOffset(Math.max(0, offset - LIMIT))} onNext={() => setOffset(offset + LIMIT)} />
+          </>
+        ) : (
+          <div className="py-12 text-center">
+            <GitCommitHorizontal className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-3 text-[13px] text-muted-foreground">No commits found</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/contributors.tsx b/src/page/workspace/repo/contributors.tsx
new file mode 100644
index 0000000..a015e96
--- /dev/null
+++ b/src/page/workspace/repo/contributors.tsx
@@ -0,0 +1,67 @@
+import { useParams, useSearchParams } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Users, GitCommitHorizontal } from "lucide-react";
+import PaginationBar from "./pagination";
+
+const LIMIT = 20;
+
+export default function ContributorsTab() {
+  const { projectName = "", repoName = "" } = useParams();
+  const [contribSearchParams, setContribSearchParams] = useSearchParams();
+  const offset = Number(contribSearchParams.get("offset") ?? "0");
+  const setOffset = (n: number) => {
+    const next = new URLSearchParams(contribSearchParams);
+    if (n <= 0) next.delete("offset"); else next.set("offset", String(n));
+    setContribSearchParams(next, { replace: true });
+  };
+
+  const { data: contributors = [], isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "contributors", offset],
+    queryFn: async () => {
+      const res = await client.gitListContributors(projectName, repoName, { params: { offset, limit: LIMIT } } as any);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const sorted = [...contributors].sort((a, b) => b.commit_count - a.commit_count);
+
+  return (
+    <div>
+      <div className="rounded-md border border-border overflow-hidden">
+        <div className="flex items-center gap-2 bg-muted/50 px-3 py-2 border-b border-border">
+          <span className="font-mono text-[11px] text-muted-foreground">Contributors</span>
+        </div>
+        {isLoading ? (
+          <div className="px-4 py-2">{Array.from({ length: 5 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}</div>
+        ) : sorted.length > 0 ? (
+          <>
+            <div>
+              {sorted.map((c) => (
+                <div className="flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0" key={c.email}>
+                  <Users className="size-4 text-muted-foreground shrink-0" />
+                  <div className="min-w-0 flex-1">
+                    <span className="font-heading text-[13px] font-semibold text-foreground">{c.name}</span>
+                    <span className="font-mono text-[11px] text-muted-foreground/60 ml-1">{c.email}</span>
+                  </div>
+                  <div className="flex items-center gap-1.5 font-mono text-[11px] text-muted-foreground">
+                    <GitCommitHorizontal className="size-3" />
+                    <span>{c.commit_count} commit{c.commit_count !== 1 ? "s" : ""}</span>
+                  </div>
+                </div>
+              ))}
+            </div>
+            <PaginationBar offset={offset} limit={LIMIT} hasMore={contributors.length >= LIMIT} onPrev={() => setOffset(Math.max(0, offset - LIMIT))} onNext={() => setOffset(offset + LIMIT)} />
+          </>
+        ) : (
+          <div className="py-12 text-center">
+            <Users className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-3 text-[13px] text-muted-foreground">No contributors found</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/index.tsx b/src/page/workspace/repo/index.tsx
new file mode 100644
index 0000000..d7e8f66
--- /dev/null
+++ b/src/page/workspace/repo/index.tsx
@@ -0,0 +1 @@
+export { default } from "./layout";
\ No newline at end of file
diff --git a/src/page/workspace/repo/layout.tsx b/src/page/workspace/repo/layout.tsx
new file mode 100644
index 0000000..828aaba
--- /dev/null
+++ b/src/page/workspace/repo/layout.tsx
@@ -0,0 +1,204 @@
+import { useParams } from "react-router";
+import { NavLink, Outlet } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Lock, Globe, Archive, GitFork, Star, Eye, EyeOff } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+function formatSize(bytes: number) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatDate(date: string) {
+  const now = new Date();
+  const d = new Date(date);
+  const diff = now.getTime() - d.getTime();
+  const days = Math.floor(diff / 86400000);
+  if (days < 1) return "today";
+  if (days === 1) return "1 day ago";
+  if (days < 30) return `${days} days ago`;
+  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
+  return `${Math.floor(days / 365)}y ago`;
+}
+
+const tabs = [
+  { label: "Code", to: "code" },
+  { label: "Commits", to: "commits" },
+  { label: "Branches", to: "branches" },
+  { label: "Tags", to: "tags" },
+  { label: "Pull Requests", to: "pulls" },
+  { label: "Contributors", to: "contributors" },
+  { label: "Webhooks", to: "webhooks" },
+  { label: "Settings", to: "settings" },
+];
+
+export default function RepoLayout() {
+  const { projectName = "", repoName = "" } = useParams();
+  const qc = useQueryClient();
+
+  const { data: repo, isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName],
+    queryFn: async () => {
+      const res = await client.gitGetRepo(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const { data: starData } = useQuery({
+    queryKey: ["repo", projectName, repoName, "star"],
+    queryFn: async () => {
+      const res: any = await client.gitStarStatus(projectName, repoName);
+      return res.data as { starred: boolean; count: number };
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const starRepo = useMutation({
+    mutationFn: async () => {
+      if (starData?.starred) { await client.gitUnstarRepo(projectName, repoName); }
+      else { await client.gitStarRepo(projectName, repoName); }
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "star"] }),
+  });
+
+  const { data: watchData } = useQuery({
+    queryKey: ["repo", projectName, repoName, "watch"],
+    queryFn: async () => {
+      const res: any = await client.gitWatchStatus(projectName, repoName);
+      return res.data as { watching: boolean; count: number };
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const watchRepo = useMutation({
+    mutationFn: async () => {
+      if (watchData?.watching) { await client.gitUnwatchRepo(projectName, repoName); }
+      else { await client.gitWatchRepo(projectName, repoName, {} as any); }
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "watch"] }),
+  });
+
+  // Check if README exists
+  const { data: readme } = useQuery({
+    queryKey: ["repo", projectName, repoName, "readme"],
+    queryFn: async () => {
+      const res = await client.gitGetReadme(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const allTabs = [
+    ...(readme?.html ? [{ label: "README", to: "readme" }] : []),
+    ...tabs,
+  ];
+
+  if (isLoading) {
+    return (
+      <div className="px-8 py-10 space-y-3">
+        <div className="h-7 animate-pulse rounded bg-muted/50 w-64" />
+        <div className="h-5 animate-pulse rounded bg-muted/50 w-80" />
+        <div className="h-4 animate-pulse rounded bg-muted/50 w-48" />
+      </div>
+    );
+  }
+
+  if (!repo) {
+    return (
+      <div className="px-8 py-10 text-center">
+        <GitFork className="mx-auto size-5 text-muted-foreground/20" />
+        <p className="mt-3 text-[13px] text-muted-foreground">Repository not found</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-6xl px-6 py-8 lg:px-8 lg:py-10">
+      {/* Header */}
+      <div className="flex items-center gap-2 flex-wrap">
+        <h1 className="font-heading text-lg font-bold text-foreground">{repo.name}</h1>
+        {repo.visibility === "private" ? (
+          <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-muted-foreground">
+            <Lock className="size-2.5" />Private
+          </span>
+        ) : (
+          <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-muted-foreground">
+            <Globe className="size-2.5" />Public
+          </span>
+        )}
+        {repo.is_archived && (
+          <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-muted-foreground">
+            <Archive className="size-2.5" />Archived
+          </span>
+        )}
+        {repo.is_mirror && (
+          <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-muted-foreground">Mirror</span>
+        )}
+        {repo.is_template && (
+          <span className="inline-flex items-center gap-1 rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-muted-foreground">Template</span>
+        )}
+      </div>
+
+      {repo.description && (
+        <p className="mt-1 text-[13px] text-muted-foreground max-w-2xl">{repo.description}</p>
+      )}
+
+      <div className="mt-2 flex items-center gap-3 font-mono text-[11px] text-muted-foreground flex-wrap">
+        <span><span className="text-foreground/60">default branch:</span> {repo.default_branch}</span>
+        <span className="text-muted-foreground/30">|</span>
+        <span>{formatSize(repo.size_bytes)}</span>
+        <span className="text-muted-foreground/30">|</span>
+        <span>created {formatDate(repo.created_at)} by {repo.created_by}</span>
+        <div className="flex items-center gap-1.5 ml-2">
+          <button
+            className={cn("inline-flex items-center gap-1 rounded-sm border px-2 py-1 text-[11px] transition-colors", starData?.starred ? "border-primary/40 bg-primary/5 text-primary" : "border-border text-muted-foreground hover:text-foreground")}
+            disabled={starRepo.isPending}
+            onClick={() => starRepo.mutate()}
+          >
+            <Star className={cn("size-3", starData?.starred && "fill-primary")} />
+            {starData?.starred ? "Starred" : "Star"}
+            {typeof starData?.count === "number" && <span className="font-mono text-[10px]">{starData.count}</span>}
+          </button>
+          <button
+            className={cn("inline-flex items-center gap-1 rounded-sm border px-2 py-1 text-[11px] transition-colors", watchData?.watching ? "border-primary/40 bg-primary/5 text-primary" : "border-border text-muted-foreground hover:text-foreground")}
+            disabled={watchRepo.isPending}
+            onClick={() => watchRepo.mutate()}
+          >
+            {watchData?.watching ? <Eye className="size-3" /> : <EyeOff className="size-3" />}
+            {watchData?.watching ? "Watching" : "Watch"}
+            {typeof watchData?.count === "number" && <span className="font-mono text-[10px]">{watchData.count}</span>}
+          </button>
+        </div>
+      </div>
+
+      {/* Tab nav */}
+      <nav className="mt-6 flex items-center gap-0 overflow-x-auto border-b border-border">
+        {allTabs.map((tab) => (
+          <NavLink
+            className={({ isActive }) => cn(
+              "inline-flex shrink-0 items-center px-3 h-8 text-[13px] font-medium border-b-2 border-transparent transition-colors -mb-px",
+              isActive ? "text-foreground border-primary" : "text-muted-foreground hover:text-foreground hover:border-muted-foreground/30",
+            )}
+            end
+            key={tab.to}
+            to={tab.to}
+          >
+            {tab.label}
+          </NavLink>
+        ))}
+      </nav>
+
+      {/* Content */}
+      <div className="mt-6">
+        <Outlet />
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/pagination.tsx b/src/page/workspace/repo/pagination.tsx
new file mode 100644
index 0000000..243df79
--- /dev/null
+++ b/src/page/workspace/repo/pagination.tsx
@@ -0,0 +1,23 @@
+import { Button } from "@/components/ui/button";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+export default function PaginationBar({ offset, limit, hasMore, onPrev, onNext }: {
+  offset: number;
+  limit: number;
+  hasMore: boolean;
+  onPrev: () => void;
+  onNext: () => void;
+}) {
+  const page = Math.floor(offset / limit) + 1;
+  return (
+    <div className="flex items-center justify-center gap-3 px-4 py-3 border-t border-border">
+      <Button className="h-7 px-2 text-[11px]" disabled={offset === 0} onClick={onPrev} variant="ghost">
+        <ChevronLeft className="size-3 mr-1" /> Prev
+      </Button>
+      <span className="font-mono text-[11px] text-muted-foreground">Page {page}</span>
+      <Button className="h-7 px-2 text-[11px]" disabled={!hasMore} onClick={onNext} variant="ghost">
+        Next <ChevronRight className="size-3 ml-1" />
+      </Button>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/pull-create.tsx b/src/page/workspace/repo/pull-create.tsx
new file mode 100644
index 0000000..a1c7738
--- /dev/null
+++ b/src/page/workspace/repo/pull-create.tsx
@@ -0,0 +1,147 @@
+import { useState, type FormEvent } from "react";
+import { Link, useNavigate, useParams } from "react-router";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { GitPullRequest, ArrowRight, ArrowLeft } from "lucide-react";
+
+export default function PullCreatePage() {
+  const { projectName = "", repoName = "" } = useParams();
+  const navigate = useNavigate();
+  const qc = useQueryClient();
+
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [sourceBranch, setSourceBranch] = useState("");
+  const [targetBranch, setTargetBranch] = useState("");
+  const [draft, setDraft] = useState(false);
+  const [error, setError] = useState("");
+
+  const { data: branches = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branches"],
+    queryFn: async () => {
+      const res = await client.gitListBranches(projectName, repoName);
+      return res.data.branches;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const createPr = useMutation({
+    mutationFn: async () => {
+      const res = await client.pullRequestCreatePr(projectName, repoName, {
+        title,
+        body: body || null,
+        source_branch: sourceBranch,
+        target_branch: targetBranch || undefined,
+        draft: draft || null,
+      });
+      return res.data;
+    },
+    onSuccess: (data) => {
+      qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] });
+      navigate(`/${projectName}/repo/${repoName}/pulls/${data.number}`);
+    },
+    onError: (err: Error) => {
+      setError(err.message);
+    },
+  });
+
+  const handleSubmit = (event: FormEvent) => {
+    event.preventDefault();
+    if (!sourceBranch) { setError("Source branch is required."); return; }
+    setError("");
+    createPr.mutate();
+  };
+
+  return (
+    <div className="mx-auto max-w-5xl px-8 py-10">
+      <Link className="inline-flex items-center gap-1 text-[12px] text-muted-foreground hover:text-foreground transition-colors mb-4" to={`/${projectName}/repo/${repoName}`}>
+        <ArrowLeft className="size-3.5" />
+        Back to repository
+      </Link>
+      <div className="flex items-center gap-2">
+        <GitPullRequest className="size-4 text-muted-foreground" />
+        <h1 className="font-heading text-lg font-bold text-foreground">New pull request</h1>
+      </div>
+
+      <form className="mt-6 grid grid-cols-[1fr_240px] gap-6" onSubmit={handleSubmit}>
+        {/* Main */}
+        <div className="space-y-4">
+          {/* Branch selector */}
+          <div className="flex items-center gap-2 rounded-md border border-border px-3 py-2.5">
+            <Select value={sourceBranch} onValueChange={(v) => setSourceBranch(v ?? "")}>
+              <SelectTrigger className="h-8 text-[12px] w-auto min-w-[140px]">
+                <SelectValue placeholder="source branch" />
+              </SelectTrigger>
+              <SelectContent>
+                {branches.filter((b) => b.name !== targetBranch).map((b) => (
+                  <SelectItem key={b.name} value={b.name}>{b.name}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            <ArrowRight className="size-3.5 text-muted-foreground shrink-0" />
+            <Select value={targetBranch} onValueChange={(v) => setTargetBranch(v ?? "")}>
+              <SelectTrigger className="h-8 text-[12px] w-auto min-w-[140px]">
+                <SelectValue placeholder="target branch" />
+              </SelectTrigger>
+              <SelectContent>
+                {branches.filter((b) => b.name !== sourceBranch).map((b) => (
+                  <SelectItem key={b.name} value={b.name}>{b.name}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div>
+            <Input
+              className="mt-1.5 h-9 text-[14px] font-heading font-semibold"
+              placeholder="Pull request title"
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+              required
+              autoFocus
+            />
+          </div>
+          <div>
+            <Textarea
+              className="mt-1.5 min-h-[200px] text-[13px]"
+              placeholder="Describe your changes... Markdown is supported"
+              value={body}
+              onChange={(e) => setBody(e.target.value)}
+            />
+          </div>
+
+          {error && <p className="text-[12px] text-destructive">{error}</p>}
+
+          <div className="flex items-center gap-3">
+            <Button className="h-9 px-4 text-[13px]" disabled={createPr.isPending || !sourceBranch || !title.trim()} type="submit">
+              {createPr.isPending ? "Creating..." : "Create pull request"}
+            </Button>
+            <Link className="inline-flex items-center h-9 px-4 text-[13px] rounded-md border border-border text-muted-foreground hover:text-foreground transition-colors" to={`/${projectName}/repo/${repoName}`}>Cancel</Link>
+          </div>
+        </div>
+
+        {/* Sidebar */}
+        <div className="space-y-4">
+          <div>
+            <label className="flex items-center gap-2 cursor-pointer">
+              <input checked={draft} className="size-3.5 rounded border-border accent-primary" onChange={(e) => setDraft(e.target.checked)} type="checkbox" />
+              <span className="text-[13px] text-foreground">Draft PR</span>
+            </label>
+            <p className="text-[11px] text-muted-foreground mt-0.5">Cannot be merged until marked ready.</p>
+          </div>
+        </div>
+      </form>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/pull-detail.tsx b/src/page/workspace/repo/pull-detail.tsx
new file mode 100644
index 0000000..a833d64
--- /dev/null
+++ b/src/page/workspace/repo/pull-detail.tsx
@@ -0,0 +1,414 @@
+import { useState } from "react";
+import { useParams, Link } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import {
+  Circle,
+  CircleDot,
+  GitMerge,
+  GitPullRequest,
+  MessageSquare,
+  Plus,
+  Minus,
+  FileCode,
+  ArrowRight,
+  ArrowLeft,
+  X,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+
+function formatDate(date: string) {
+  return new Date(date).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
+
+function AuthorAvatar({ author }: { author: { username: string; display_name?: string | null; avatar_url?: string | null } }) {
+  const name = author.display_name ?? author.username;
+  return (
+    <span
+      className={cn("grid size-6 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white", workspaceColor(name))}
+    >
+      {author.avatar_url ? <img alt="" className="size-full object-cover" src={author.avatar_url} /> : workspaceInitial(name)}
+    </span>
+  );
+}
+
+function LabelBadge({ label }: { label: { name: string; color: string } }) {
+  return (
+    <span
+      className="inline-flex h-[18px] items-center rounded px-1.5 text-[11px] font-medium leading-none whitespace-nowrap"
+      style={{ backgroundColor: label.color + "18", color: label.color }}
+    >
+      {label.name}
+    </span>
+  );
+}
+
+export default function PullDetailPage() {
+  const { projectName = "", repoName = "", number = "" } = useParams();
+  const prNumber = Number(number);
+  const qc = useQueryClient();
+  const [showCommentInput, setShowCommentInput] = useState(false);
+  const [commentBody, setCommentBody] = useState("");
+  const [editing, setEditing] = useState(false);
+  const [editTitle, setEditTitle] = useState("");
+  const [editBody, setEditBody] = useState("");
+  const [assignUsername, setAssignUsername] = useState("");
+  const [addLabelName, setAddLabelName] = useState("");
+  const [editDraft, setEditDraft] = useState(false);
+
+  const { data: pr, isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "pulls", prNumber],
+    queryFn: async () => {
+      const res = await client.pullRequestGetPr(projectName, repoName, prNumber);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName) && prNumber > 0,
+    retry: false,
+  });
+
+  // Diff between source and target
+  const { data: diffData } = useQuery({
+    queryKey: ["repo", projectName, repoName, "pr-diff", prNumber],
+    queryFn: async () => {
+      if (!pr) return null;
+      const res = await client.gitDiff(projectName, repoName, { old_oid: pr.target_sha, new_oid: pr.source_sha });
+      return res.data;
+    },
+    enabled: Boolean(pr?.source_sha && pr?.target_sha),
+    retry: false,
+  });
+
+  const { data: comments = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "pulls", prNumber, "comments"],
+    queryFn: async () => {
+      const res = await client.pullRequestListComments(projectName, repoName, prNumber);
+      return res.data;
+    },
+    enabled: prNumber > 0,
+    retry: false,
+  });
+
+  const closePr = useMutation({
+    mutationFn: () => (client as any).pullRequestMergePr(projectName, repoName, prNumber),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }),
+  });
+
+  const reopenPr = useMutation({
+    mutationFn: () => (client as any).pullRequestUpdatePr(projectName, repoName, prNumber),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }),
+  });
+
+  const mergePr = useMutation({
+    mutationFn: () => client.pullRequestMergePr(projectName, repoName, prNumber, { method: "merge" }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }),
+  });
+
+  const { data: mergeAnalysis } = useQuery({
+    queryKey: ["repo", projectName, repoName, "pulls", prNumber, "merge-analysis"],
+    queryFn: async () => {
+      const res: any = await client.pullRequestMergeAnalysis(projectName, repoName, prNumber);
+      return res.data as { mergeable: boolean };
+    },
+    enabled: prNumber > 0,
+    retry: false,
+  });
+
+  const updateBranch = useMutation({
+    mutationFn: () => client.pullRequestUpdateBranch(projectName, repoName, prNumber),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }),
+  });
+
+  const updatePr = useMutation({
+    mutationFn: () => client.pullRequestUpdatePr(projectName, repoName, prNumber, { title: editTitle, body: editBody || null, draft: editDraft || null }),
+    onSuccess: () => { setEditing(false); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }); },
+  });
+
+  const assignUser = useMutation({
+    mutationFn: () => client.pullRequestAssignUser(projectName, repoName, prNumber, { username: assignUsername }),
+    onSuccess: () => { setAssignUsername(""); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }); },
+  });
+
+  const unassignUser = useMutation({
+    mutationFn: () => client.pullRequestUnassignUser(projectName, repoName, prNumber),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }),
+  });
+
+  const addLabel = useMutation({
+    mutationFn: () => client.pullRequestAddLabel(projectName, repoName, prNumber, { name: addLabelName } as any),
+    onSuccess: () => { setAddLabelName(""); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }); },
+  });
+
+  const removeLabel = useMutation({
+    mutationFn: (name: string) => client.pullRequestRemoveLabel(projectName, repoName, prNumber, { name } as any),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls"] }),
+  });
+
+  const addComment = useMutation({
+    mutationFn: () => client.pullRequestCreateComment(projectName, repoName, prNumber, { body: commentBody }),
+    onSuccess: () => {
+      setCommentBody("");
+      setShowCommentInput(false);
+      qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "pulls", prNumber, "comments"] });
+    },
+  });
+
+  if (isLoading) {
+    return (
+      <div className="px-8 py-10 space-y-3">
+        <div className="h-7 animate-pulse rounded bg-muted/50 w-64" />
+        <div className="h-24 animate-pulse rounded bg-muted/50" />
+      </div>
+    );
+  }
+
+  if (!pr) {
+    return (
+      <div className="px-8 py-10 text-center">
+        <GitPullRequest className="mx-auto size-5 text-muted-foreground/20" />
+        <p className="mt-3 text-[13px] text-muted-foreground">Pull request not found</p>
+      </div>
+    );
+  }
+
+  const isOpen = pr.state === "open" && !pr.merged_at;
+
+  return (
+    <div className="mx-auto max-w-5xl px-8 py-10">
+      {/* Back link */}
+      <Link className="inline-flex items-center gap-1 text-[12px] text-muted-foreground hover:text-foreground transition-colors mb-4" to={`/${projectName}/repo/${repoName}`}>
+        <ArrowLeft className="size-3.5" />
+        Back to repository
+      </Link>
+
+      {/* Header */}
+      <div className="flex items-center gap-2">
+        {pr.merged_at ? (
+          <GitMerge className="size-5 text-purple-600 shrink-0" />
+        ) : isOpen ? (
+          <Circle className="size-5 text-green-600 shrink-0" />
+        ) : (
+          <CircleDot className="size-5 text-red-600 shrink-0" />
+        )}
+        <h1 className="font-heading text-[15px] font-bold text-foreground">{pr.title}</h1>
+        <span className="font-mono text-[12px] text-muted-foreground/60"># {pr.number}</span>
+      </div>
+
+      <div className="mt-2 flex items-center gap-2 text-[12px] text-muted-foreground flex-wrap">
+        <AuthorAvatar author={pr.author} />
+        <span className="font-medium text-foreground">{pr.author.display_name ?? pr.author.username}</span>
+        <span>{pr.merged_at ? "merged" : pr.state === "closed" ? "closed" : "opened"} {formatDate(pr.created_at)}</span>
+        {pr.draft && <span className="rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px]">Draft</span>}
+        <span className="font-mono text-[11px] text-muted-foreground/60">{pr.source_branch} → {pr.target_branch}</span>
+      </div>
+
+      {/* Action buttons */}
+      {isOpen && (
+        <div className="mt-3 flex items-center gap-2">
+          {mergeAnalysis && (
+            <span className="font-mono text-[11px] text-muted-foreground mr-1">
+              {mergeAnalysis.mergeable ? "Mergeable" : "Merge conflicts"}
+            </span>
+          )}
+          <Button className="h-8 px-3 text-[12px]" disabled={mergePr.isPending} onClick={() => mergePr.mutate()}>
+            <GitMerge className="size-3.5 mr-1" /> Merge
+          </Button>
+          <Button className="h-8 px-3 text-[12px]" disabled={updateBranch.isPending} onClick={() => updateBranch.mutate()} variant="outline">
+            Update branch
+          </Button>
+          <Button className="h-8 px-3 text-[12px]" disabled={closePr.isPending} onClick={() => closePr.mutate()} variant="outline">
+            <X className="size-3.5 mr-1" /> Close
+          </Button>
+          <Button className="h-8 px-3 text-[12px]" onClick={() => { setEditing(true); setEditTitle(pr.title); setEditBody(pr.body ?? ""); setEditDraft(pr.draft); }} variant="outline">
+            {editing ? "Cancel" : "Edit"}
+          </Button>
+        </div>
+      )}
+      {pr.state === "closed" && !pr.merged_at && (
+        <div className="mt-3">
+          <Button className="h-8 px-3 text-[12px]" onClick={() => reopenPr.mutate()}>
+            Reopen
+          </Button>
+        </div>
+      )}
+
+      {/* Edit PR form */}
+      {editing && (
+        <div className="mt-4 rounded-md border border-border p-4 space-y-3">
+          <Input className="h-9 text-[14px] font-heading font-semibold" value={editTitle} onChange={(e) => setEditTitle(e.target.value)} placeholder="Title" />
+          <Textarea className="min-h-[120px] text-[13px]" value={editBody} onChange={(e) => setEditBody(e.target.value)} placeholder="Body" />
+          <label className="flex items-center gap-2 cursor-pointer">
+            <input checked={editDraft} className="size-3.5 rounded border-border accent-primary" onChange={(e) => setEditDraft(e.target.checked)} type="checkbox" />
+            <span className="text-[13px] text-foreground">Draft</span>
+          </label>
+          <div className="flex gap-2">
+            <Button className="h-8 px-3 text-[12px]" disabled={!editTitle.trim() || updatePr.isPending} onClick={() => updatePr.mutate()}>Save</Button>
+            <Button className="h-8 px-3 text-[12px]" onClick={() => setEditing(false)} variant="outline">Cancel</Button>
+          </div>
+        </div>
+      )}
+
+      <div className="mt-6 grid grid-cols-[1fr_220px] gap-6">
+        {/* Main */}
+        <div className="space-y-5">
+          {/* Labels */}
+          {pr.labels.length > 0 && (
+            <div className="flex items-center gap-1.5">{pr.labels.map((l) => <LabelBadge key={l.id} label={l} />)}</div>
+          )}
+
+          {/* Body */}
+          {pr.body ? (
+            <div className="rounded-md border border-border overflow-hidden">
+              <div className="flex items-center gap-2 bg-muted/30 px-4 py-2 border-b border-border">
+                <AuthorAvatar author={pr.author} />
+                <span className="font-heading text-[13px] font-medium text-foreground">{pr.author.display_name ?? pr.author.username}</span>
+                <span className="font-mono text-[11px] text-muted-foreground ml-auto">{formatDate(pr.created_at)}</span>
+              </div>
+              <div className="px-4 py-3 text-[13px] text-foreground whitespace-pre-wrap leading-relaxed">{pr.body}</div>
+            </div>
+          ) : (
+            <div className="rounded-md border border-border px-4 py-6 text-center text-[12px] text-muted-foreground">No description provided.</div>
+          )}
+
+          {/* Diff stats */}
+          {(diffData as any)?.stats && (
+            <div>
+              <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-2">Files changed</p>
+              <div className="flex items-center gap-4 text-[12px] mb-3">
+                <span className="font-mono text-muted-foreground">{ (diffData as any).stats.files_changed} files</span>
+                <span className="flex items-center gap-1 text-green-600 font-mono"><Plus className="size-3" />{ (diffData as any).stats.insertions}</span>
+                <span className="flex items-center gap-1 text-red-600 font-mono"><Minus className="size-3" />{ (diffData as any).stats.deletions}</span>
+              </div>
+              <div className="space-y-2">
+                {(diffData as any).deltas.map((delta: any, i: number) => {
+                  const path = delta.new_file?.path ?? delta.old_file?.path ?? "unknown";
+                  return (
+                    <div className="rounded-md border border-border overflow-hidden" key={i}>
+                      <div className="flex items-center gap-2 bg-muted/30 px-3 py-1.5 border-b border-border">
+                        <FileCode className="size-3.5 text-muted-foreground shrink-0" />
+                        <span className="font-heading text-[12px] font-medium text-foreground truncate">{path}</span>
+                      </div>
+                      {delta.lines.length > 0 && (
+                        <div className="overflow-auto max-h-[300px]">
+                          <table className="w-full font-mono text-[11px] leading-relaxed">
+                            <tbody>
+                              {delta.lines.map((line: any, j: number) => (
+                                <tr className={cn(line.origin === "+" && "bg-green-950/20", line.origin === "-" && "bg-red-950/20")} key={j}>
+                                  <td className="w-10 text-right px-1.5 text-muted-foreground/40 select-none border-r border-border">{line.old_lineno ?? ""}</td>
+                                  <td className="w-10 text-right px-1.5 text-muted-foreground/40 select-none border-r border-border">{line.new_lineno ?? ""}</td>
+                                  <td className="w-3 text-center text-muted-foreground/50 select-none">{line.origin}</td>
+                                  <td className={cn("px-2 whitespace-pre", line.origin === "+" ? "text-green-400" : line.origin === "-" ? "text-red-400" : "text-foreground")}>{line.content}</td>
+                                </tr>
+                              ))}
+                            </tbody>
+                          </table>
+                        </div>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* Comments */}
+          <div>
+            <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-2">
+              {comments.length > 0 ? `${comments.length} comment${comments.length > 1 ? "s" : ""}` : "Comments"}
+            </p>
+            <div className="space-y-3">
+              {comments.map((c) => (
+                <div className="rounded-md border border-border overflow-hidden" key={c.id}>
+                  <div className="flex items-center gap-2 bg-muted/30 px-3 py-1.5 border-b border-border">
+                    <AuthorAvatar author={c.author} />
+                    <span className="font-heading text-[12px] font-medium text-foreground">{c.author.display_name ?? c.author.username}</span>
+                    <span className="font-mono text-[11px] text-muted-foreground ml-auto">{formatDate(c.created_at)}</span>
+                  </div>
+                  <div className="px-3 py-2 text-[13px] text-foreground whitespace-pre-wrap">{c.body}</div>
+                </div>
+              ))}
+            </div>
+            {showCommentInput ? (
+              <div className="mt-3 space-y-2">
+                <Textarea
+                  className="min-h-[100px] text-[13px]"
+                  placeholder="Leave a comment..."
+                  value={commentBody}
+                  onChange={(e) => setCommentBody(e.target.value)}
+                />
+                <div className="flex items-center gap-2">
+                  <Button className="h-8 px-3 text-[12px]" disabled={!commentBody.trim()} onClick={() => addComment.mutate()}>Comment</Button>
+                  <Button className="h-8 px-3 text-[12px]" onClick={() => { setShowCommentInput(false); setCommentBody(""); }} variant="outline">Cancel</Button>
+                </div>
+              </div>
+            ) : (
+              <Button className="mt-3 h-8 px-3 text-[12px]" onClick={() => setShowCommentInput(true)} variant="outline">
+                <MessageSquare className="size-3.5 mr-1" /> Leave a comment
+              </Button>
+            )}
+          </div>
+        </div>
+
+        {/* Sidebar */}
+        <div className="rounded-md border border-border overflow-hidden">
+          <SidebarSection title="Status">
+            {pr.merged_at ? (
+              <span className="text-[12px] text-purple-600 font-heading font-medium">Merged</span>
+            ) : pr.state === "open" ? (
+              <span className="text-[12px] text-green-600 font-heading font-medium">Open</span>
+            ) : (
+              <span className="text-[12px] text-red-600 font-heading font-medium">Closed</span>
+            )}
+          </SidebarSection>
+
+          <SidebarSection title="Assignees">
+            {pr.assignees.length > 0 ? pr.assignees.map((a) => (
+              <div className="flex items-center gap-1.5" key={a.username}>
+                <AuthorAvatar author={a} />
+                <span className="text-[12px] text-foreground">{a.display_name ?? a.username}</span>
+                <button className="ml-auto text-[10px] text-muted-foreground hover:text-destructive" onClick={() => unassignUser.mutate()}>&times;</button>
+              </div>
+            )) : <span className="text-[12px] text-muted-foreground">No one assigned</span>}
+            <div className="mt-1.5 flex items-center gap-1">
+              <Input className="h-6 w-full text-[11px]" placeholder="Username" value={assignUsername} onChange={(e) => setAssignUsername(e.target.value)} />
+              <Button className="h-6 px-2 text-[10px]" disabled={!assignUsername.trim()} onClick={() => assignUser.mutate()} variant="outline">Add</Button>
+            </div>
+          </SidebarSection>
+
+          <SidebarSection title="Labels">
+            {pr.labels.length > 0 ? pr.labels.map((l) => (
+              <div className="flex items-center gap-1.5" key={l.id}>
+                <span className="inline-flex h-[18px] items-center rounded px-1.5 text-[11px] font-medium" style={{ backgroundColor: l.color + "18", color: l.color }}>{l.name}</span>
+                <button className="ml-auto text-[10px] text-muted-foreground hover:text-destructive" onClick={() => removeLabel.mutate(l.name)}>&times;</button>
+              </div>
+            )) : <span className="text-[12px] text-muted-foreground">No labels</span>}
+            <div className="mt-1.5 flex items-center gap-1">
+              <Input className="h-6 w-full text-[11px]" placeholder="Label name" value={addLabelName} onChange={(e) => setAddLabelName(e.target.value)} />
+              <Button className="h-6 px-2 text-[10px]" disabled={!addLabelName.trim()} onClick={() => addLabel.mutate()} variant="outline">Add</Button>
+            </div>
+          </SidebarSection>
+
+          <SidebarSection title="Branches">
+            <div className="flex items-center gap-1 text-[12px]">
+              <code className="font-mono text-primary">{pr.source_branch}</code>
+              <ArrowRight className="size-3 text-muted-foreground" />
+              <code className="font-mono text-foreground">{pr.target_branch}</code>
+            </div>
+          </SidebarSection>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function SidebarSection({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="border-b border-border last:border-b-0 py-3 px-3">
+      <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-1.5">{title}</p>
+      {children}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/pulls.tsx b/src/page/workspace/repo/pulls.tsx
new file mode 100644
index 0000000..836cc25
--- /dev/null
+++ b/src/page/workspace/repo/pulls.tsx
@@ -0,0 +1,185 @@
+import { useState } from "react";
+import { Link, useParams, useSearchParams } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { client, type PullRequestResponse } from "@/client";
+import {
+  Circle,
+  CircleDot,
+  GitMerge,
+  GitPullRequest,
+  Search,
+  Plus,
+} from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import PaginationBar from "./pagination";
+
+function formatDate(date: string) {
+  const now = new Date();
+  const d = new Date(date);
+  const diff = now.getTime() - d.getTime();
+  const days = Math.floor(diff / 86400000);
+  if (days < 1) return "today";
+  if (days === 1) return "1 day ago";
+  if (days < 30) return `${days} days ago`;
+  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
+  return `${Math.floor(days / 365)}y ago`;
+}
+
+function AuthorAvatar({ author }: { author: { username: string; avatar_url?: string | null; display_name?: string | null } }) {
+  const name = author.display_name ?? author.username;
+  return (
+    <span
+      className={cn(
+        "grid size-5 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-[10px] font-bold text-white",
+        workspaceColor(name),
+      )}
+    >
+      {author.avatar_url ? (
+        <img alt="" className="size-full object-cover" src={author.avatar_url} />
+      ) : (
+        workspaceInitial(name)
+      )}
+    </span>
+  );
+}
+
+function LabelBadge({ label }: { label: { name: string; color: string } }) {
+  return (
+    <span
+      className="inline-flex h-[18px] items-center rounded px-1.5 text-[11px] font-medium leading-none whitespace-nowrap"
+      style={{ backgroundColor: label.color + "18", color: label.color }}
+    >
+      {label.name}
+    </span>
+  );
+}
+
+function PullStateIcon({ pr }: { pr: PullRequestResponse }) {
+  if (pr.merged_at) {
+    return <GitMerge className="size-[14px] text-purple-600 shrink-0 mt-0.5" />;
+  }
+  if (pr.state === "closed") {
+    return <CircleDot className="size-[14px] text-red-600 shrink-0 mt-0.5" />;
+  }
+  return <Circle className="size-[14px] text-green-600 shrink-0 mt-0.5" />;
+}
+
+function PullRow({ pr, projectName, repoName }: { pr: PullRequestResponse; projectName: string; repoName: string }) {
+  return (
+    <Link
+      className="group flex items-start gap-3 border-b border-border px-4 py-2.5 last:border-b-0 transition-colors hover:bg-muted/40"
+      to={`/${projectName}/repo/${repoName}/pulls/${pr.number}`}
+    >
+      <PullStateIcon pr={pr} />
+      <div className="min-w-0 flex-1">
+        <div className="flex items-baseline gap-1.5 flex-wrap">
+          <span className="font-heading text-[13px] font-semibold text-foreground leading-tight">{pr.title}</span>
+          <span className="font-mono text-[11px] text-muted-foreground/60"># {pr.number}</span>
+          {pr.draft && (
+            <span className="rounded-sm border border-border px-1 py-0.5 font-mono text-[10px] text-muted-foreground leading-none">
+              Draft
+            </span>
+          )}
+          {pr.labels.map((label) => <LabelBadge key={label.id} label={label} />)}
+        </div>
+        <div className="mt-0.5 flex items-center gap-2 text-[11px] text-muted-foreground flex-wrap">
+          <span className="flex items-center gap-1">
+            <AuthorAvatar author={pr.author} />
+            {pr.author.display_name ?? pr.author.username}
+          </span>
+          <span>opened {formatDate(pr.created_at)}</span>
+          <span className="font-mono text-[10px] text-muted-foreground/60">
+            {pr.source_branch} → {pr.target_branch}
+          </span>
+        </div>
+      </div>
+    </Link>
+  );
+}
+
+const LIMIT = 20;
+
+export default function PullsTab() {
+  const { projectName = "", repoName = "" } = useParams();
+  const [stateFilter, setStateFilter] = useState<string>("open");
+  const [search, setSearch] = useState("");
+  const [pullsSearchParams, setPullsSearchParams] = useSearchParams();
+  const offset = Number(pullsSearchParams.get("offset") ?? "0");
+  const setOffset = (n: number) => {
+    const next = new URLSearchParams(pullsSearchParams);
+    if (n <= 0) next.delete("offset"); else next.set("offset", String(n));
+    setPullsSearchParams(next, { replace: true });
+  };
+
+  const { data: prs = [], isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "pulls", stateFilter, offset],
+    queryFn: async () => {
+      const res = await client.pullRequestListPrs(projectName, repoName, { state: stateFilter === "all" ? undefined : stateFilter, offset, limit: LIMIT });
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const filteredPrs = search
+    ? prs.filter((pr) => pr.title.toLowerCase().includes(search.toLowerCase()) || String(pr.number).includes(search))
+    : prs;
+
+  const openCount = prs.filter((pr) => pr.state === "open" && !pr.merged_at).length;
+  const closedCount = prs.filter((pr) => pr.state === "closed" || pr.merged_at).length;
+
+  return (
+    <div>
+      <div className="rounded-md border border-border overflow-hidden">
+        <div className="flex items-center gap-2 bg-muted/50 px-3 py-2 border-b border-border">
+          <nav className="flex items-center">
+            {[
+              { key: "open", icon: <Circle className="size-3 text-green-600" />, count: openCount },
+              { key: "closed", icon: <CircleDot className="size-3 text-red-600" />, count: closedCount },
+              { key: "all", icon: <GitPullRequest className="size-3" />, count: prs.length },
+            ].map((tab) => (
+              <button
+                className={cn("flex items-center gap-1.5 px-2.5 py-1 text-[12px] font-medium transition-colors rounded-sm", stateFilter === tab.key ? "text-foreground bg-muted/70" : "text-muted-foreground hover:text-foreground")}
+                key={tab.key}
+                onClick={() => { setStateFilter(tab.key); setOffset(0); }}
+              >
+                {tab.icon}
+                {tab.key === "all" ? "All" : tab.key.charAt(0).toUpperCase() + tab.key.slice(1)}
+                <span className="font-mono text-[10px] text-muted-foreground">{tab.count}</span>
+              </button>
+            ))}
+          </nav>
+          <div className="ml-auto flex items-center gap-2">
+            <Link className="h-7 px-2 inline-flex items-center text-[12px] font-medium rounded-sm border border-border text-muted-foreground hover:text-foreground transition-colors" to={`/${projectName}/repo/${repoName}/pulls/new`}>
+              <Plus className="size-3 mr-1" />New PR
+            </Link>
+            <div className="relative">
+              <Search className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+              <Input className="h-7 w-52 rounded-sm border-border bg-card pl-7 text-[12px]" placeholder="Filter PRs..." value={search} onChange={(e) => setSearch(e.target.value)} />
+            </div>
+          </div>
+        </div>
+
+        {isLoading ? (
+          <div className="px-4 py-2">
+            {Array.from({ length: 3 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}
+          </div>
+        ) : filteredPrs.length > 0 ? (
+          <>
+          <div>{filteredPrs.map((pr) => <PullRow key={pr.number} pr={pr} projectName={projectName} repoName={repoName} />)}</div>
+          <PaginationBar offset={offset} limit={LIMIT} hasMore={prs.length >= LIMIT} onPrev={() => setOffset(Math.max(0, offset - LIMIT))} onNext={() => setOffset(offset + LIMIT)} />
+          </>
+        ) : (
+          <div className="py-12 text-center">
+            <GitPullRequest className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-3 text-[13px] text-muted-foreground">
+              {stateFilter === "open" ? "No open pull requests" : stateFilter === "closed" ? "No closed pull requests" : "No pull requests yet"}
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/readme-page.tsx b/src/page/workspace/repo/readme-page.tsx
new file mode 100644
index 0000000..b58fe19
--- /dev/null
+++ b/src/page/workspace/repo/readme-page.tsx
@@ -0,0 +1,48 @@
+import { useParams } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { client } from "@/client";
+import { BookOpen } from "lucide-react";
+
+const SKELETON_WIDTHS = Array.from({ length: 8 }, () => 30 + Math.floor(Math.random() * 60));
+
+export default function ReadmePage() {
+  const { projectName = "", repoName = "" } = useParams();
+
+  const { data: readme, isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "readme"],
+    queryFn: async () => {
+      const res = await client.gitGetReadme(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  if (isLoading) {
+    return <div className="space-y-3">{SKELETON_WIDTHS.map((w, i) => <div className="h-4 animate-pulse rounded bg-muted/50" key={i} style={{ width: `${w}%` }} />)}</div>;
+  }
+
+  if (!readme?.html) {
+    return (
+      <div className="py-12 text-center">
+        <BookOpen className="mx-auto size-5 text-muted-foreground/20" />
+        <p className="mt-2 text-[13px] text-muted-foreground">No README found</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-3xl">
+      <div className="rounded-md border border-border overflow-hidden">
+        <div className="flex items-center gap-2 bg-muted/50 px-4 py-2 border-b border-border">
+          <BookOpen className="size-4 text-muted-foreground" />
+          <span className="font-heading text-[13px] font-medium text-foreground">README.md</span>
+        </div>
+        <div
+          className="px-6 py-4 text-[14px] leading-relaxed [&_h1]:text-lg [&_h1]:font-bold [&_h1]:font-heading [&_h1]:mb-3 [&_h1]:mt-6 [&_h1:first-child]:mt-0 [&_h2]:text-base [&_h2]:font-bold [&_h2]:font-heading [&_h2]:mb-2 [&_h2]:mt-5 [&_h3]:text-[15px] [&_h3]:font-bold [&_h3]:mb-2 [&_h3]:mt-4 [&_h4]:text-[14px] [&_h4]:font-bold [&_h4]:mb-1 [&_h4]:mt-3 [&_p]:mb-3 [&_p:last-child]:mb-0 [&_a]:text-primary [&_a]:underline [&_a:hover]:opacity-80 [&_ul]:list-disc [&_ul]:pl-6 [&_ul]:mb-3 [&_ol]:list-decimal [&_ol]:pl-6 [&_ol]:mb-3 [&_li]:mb-1 [&_code]:rounded-sm [&_code]:bg-muted [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[12px] [&_pre]:rounded-md [&_pre]:bg-muted [&_pre]:p-4 [&_pre]:mb-3 [&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_pre_code]:text-[12px] [&_blockquote]:border-l-2 [&_blockquote]:border-primary/30 [&_blockquote]:pl-4 [&_blockquote]:py-0.5 [&_blockquote]:mb-3 [&_blockquote]:text-muted-foreground [&_img]:rounded-md [&_img]:max-w-full [&_img]:my-3 [&_hr]:border-border [&_hr]:my-4 [&_table]:w-full [&_table]:border-collapse [&_table]:mb-3 [&_th]:border [&_th]:border-border [&_th]:px-3 [&_th]:py-2 [&_th]:bg-muted/50 [&_th]:text-left [&_th]:font-heading [&_th]:text-[13px] [&_td]:border [&_td]:border-border [&_td]:px-3 [&_td]:py-2"
+          dangerouslySetInnerHTML={{ __html: readme.html }}
+        />
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/settings.tsx b/src/page/workspace/repo/settings.tsx
new file mode 100644
index 0000000..762b3eb
--- /dev/null
+++ b/src/page/workspace/repo/settings.tsx
@@ -0,0 +1,282 @@
+import { useState, type FormEvent } from "react";
+import { useParams, useNavigate } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import { Lock, Globe, Archive, ArchiveRestore, Shield, Hash, Trash2, ArrowRight, GitFork } from "lucide-react";
+
+export default function RepoSettingsTab() {
+  const { projectName = "", repoName = "" } = useParams();
+  const qc = useQueryClient();
+  const navigate = useNavigate();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  const { data: repo } = useQuery({
+    queryKey: ["repo", projectName, repoName],
+    queryFn: async () => {
+      const res = await client.gitGetRepo(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const [visibility, setVisibility] = useState(repo?.visibility ?? "private");
+  const [isArchived, setIsArchived] = useState(repo?.is_archived ?? false);
+  const [defaultBranch, setDefaultBranch] = useState(repo?.default_branch ?? "");
+
+  // Topics state
+  const [topicsInput, setTopicsInput] = useState("");
+  const [transferTarget, setTransferTarget] = useState("");
+
+  const { data: branches } = useQuery({
+    queryKey: ["repo", projectName, repoName, "branches"],
+    queryFn: async () => {
+      const res = await client.gitListBranches(projectName, repoName);
+      return res.data.branches;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const { data: topics = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "topics"],
+    queryFn: async () => {
+      const res = await client.gitGetTopics(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const { data: protects = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "protects"],
+    queryFn: async () => {
+      const res = await client.gitListProtects(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const { data: forks = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "forks"],
+    queryFn: async () => {
+      const res = await client.gitListForks(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const hasBranches = branches && branches.length > 0;
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+    const form = new FormData(event.currentTarget);
+    const name = (form.get("name") as string) || null;
+    const description = (form.get("description") as string) || null;
+    try {
+      await client.gitUpdateRepo(projectName, repoName, { name, description, visibility, default_branch: defaultBranch, is_archived: isArchived });
+      await qc.invalidateQueries({ queryKey: ["repo", projectName, repoName] });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to update repository.");
+    } finally { setSubmitting(false); }
+  };
+
+  const updateTopics = useMutation({
+    mutationFn: async () => {
+      const list = topicsInput.split(",").map((t) => t.trim()).filter(Boolean);
+      await client.gitUpdateTopics(projectName, repoName, list);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "topics"] }),
+  });
+
+  const deleteRepo = useMutation({
+    mutationFn: async () => { await client.gitDeleteRepo(projectName, repoName); },
+    onSuccess: () => { navigate(`/${projectName}/repos`); },
+  });
+
+  const transferRepo = useMutation({
+    mutationFn: async () => { await client.gitTransferRepo(projectName, repoName, { target_workspace: transferTarget }); },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName] }),
+  });
+
+  const createProtect = useMutation({
+    mutationFn: async (pattern: string) => { await client.gitCreateProtect(projectName, repoName, { pattern, require_pull_request: true, required_approvals: 1 }); },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "protects"] }),
+  });
+
+  const deleteProtect = useMutation({
+    mutationFn: async (id: string) => { await client.gitDeleteProtect(projectName, repoName, id); },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "protects"] }),
+  });
+
+  const [newProtectPattern, setNewProtectPattern] = useState("");
+
+  if (!repo) {
+    return (
+      <div className="space-y-3">
+        {Array.from({ length: 4 }).map((_, i) => <div className="h-8 animate-pulse rounded bg-muted/50" key={i} />)}
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-8">
+      {/* Repo settings form */}
+      <form className="space-y-5" onSubmit={(e) => void handleSubmit(e)}>
+        <h2 className="font-heading text-[15px] font-bold text-foreground">General</h2>
+        <div>
+          <label className="text-[13px] font-medium text-foreground">Repository name</label>
+          <Input className="mt-1.5 h-9 text-[13px]" name="name" defaultValue={repo.name} />
+          <p className="mt-1 text-[11px] text-muted-foreground">Changing the name will also change the repository URL.</p>
+        </div>
+        <div>
+          <label className="text-[13px] font-medium text-foreground">Description <span className="text-muted-foreground">(optional)</span></label>
+          <Textarea className="mt-1.5 min-h-[72px] text-[13px]" name="description" defaultValue={repo.description ?? ""} />
+        </div>
+        <div>
+          <label className="text-[13px] font-medium text-foreground">Default branch</label>
+          {hasBranches ? (
+            <Select value={defaultBranch} onValueChange={(v) => setDefaultBranch(v ?? "")}>
+              <SelectTrigger className="mt-1.5 h-9 w-48 text-[13px]"><SelectValue /></SelectTrigger>
+              <SelectContent>{branches!.map((b) => <SelectItem key={b.name} value={b.name}>{b.name}</SelectItem>)}</SelectContent>
+            </Select>
+          ) : (
+            <Input className="mt-1.5 h-9 w-48 text-[13px]" name="default_branch" defaultValue={repo.default_branch} onChange={(e) => setDefaultBranch(e.target.value)} />
+          )}
+        </div>
+        <div>
+          <label className="text-[13px] font-medium text-foreground">Visibility</label>
+          <div className="mt-1.5 flex gap-2">
+            {[
+              { value: "private", icon: <Lock className="size-3.5" />, label: "Private", desc: "Only members can see this repository" },
+              { value: "public", icon: <Globe className="size-3.5" />, label: "Public", desc: "Anyone can see this repository" },
+            ].map((opt) => (
+              <button className={cn("flex items-start gap-2 rounded-md border p-3 text-left transition-colors", visibility === opt.value ? "border-primary bg-primary/5" : "border-border hover:border-muted-foreground/30")} key={opt.value} onClick={() => setVisibility(opt.value)} type="button">
+                <span className={cn("mt-0.5", visibility === opt.value ? "text-primary" : "text-muted-foreground")}>{opt.icon}</span>
+                <div>
+                  <span className={cn("text-[13px] font-medium", visibility === opt.value ? "text-foreground" : "text-muted-foreground")}>{opt.label}</span>
+                  <p className="text-[11px] text-muted-foreground">{opt.desc}</p>
+                </div>
+              </button>
+            ))}
+          </div>
+        </div>
+        <div>
+          <label className="flex items-center gap-2 cursor-pointer">
+            <input checked={isArchived} className="size-3.5 rounded border-border accent-primary" onChange={(e) => setIsArchived(e.target.checked)} type="checkbox" />
+            <span className="text-[13px] text-foreground">Archive this repository</span>
+            <span className="text-[11px] text-muted-foreground">{isArchived ? <ArchiveRestore className="size-3 inline" /> : <Archive className="size-3 inline" />}{isArchived ? " Unarchive to allow changes" : " Read-only, no changes allowed"}</span>
+          </label>
+        </div>
+        {error && <p className="text-[12px] text-destructive">{error}</p>}
+        <div className="flex items-center gap-3 pt-2">
+          <Button className="h-9 px-4 text-[13px]" disabled={submitting} type="submit">{submitting ? "Saving..." : "Save changes"}</Button>
+        </div>
+      </form>
+
+      {/* Topics */}
+      <div className="space-y-3">
+        <h2 className="font-heading text-[15px] font-bold text-foreground flex items-center gap-2"><Hash className="size-4" /> Topics</h2>
+        <div className="flex flex-wrap gap-1.5 mb-2">
+          {topics.map((t) => (
+            <span className="inline-flex items-center gap-1 rounded-full bg-primary/10 px-2.5 py-0.5 font-mono text-[11px] text-primary" key={t}>
+              #{t}
+              <button className="text-primary/60 hover:text-primary" onClick={() => {
+                const next = topics.filter((x) => x !== t);
+                client.gitUpdateTopics(projectName, repoName, next);
+                qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "topics"] });
+              }}>&times;</button>
+            </span>
+          ))}
+        </div>
+        <div className="flex items-center gap-2">
+          <Input className="h-9 text-[13px] flex-1" placeholder="e.g. rust, cli, database" value={topicsInput} onChange={(e) => setTopicsInput(e.target.value)} />
+          <Button className="h-9 px-3 text-[13px]" disabled={!topicsInput.trim() || updateTopics.isPending} onClick={() => updateTopics.mutate()}>Update</Button>
+        </div>
+      </div>
+
+      {/* Fork info */}
+      {forks.length > 0 && (
+        <div className="space-y-3">
+          <h2 className="font-heading text-[15px] font-bold text-foreground flex items-center gap-2"><GitFork className="size-4" /> Forks ({forks.length})</h2>
+          <div className="rounded-md border border-border overflow-hidden">
+            {forks.map((f) => (
+              <div className="flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0" key={f.id}>
+                <GitFork className="size-4 text-muted-foreground shrink-0" />
+                <span className="font-heading text-[13px] font-semibold text-foreground">{f.name}</span>
+                <span className="font-mono text-[10px] text-muted-foreground">{f.visibility}</span>
+                {f.forked_by && <span className="font-mono text-[11px] text-muted-foreground ml-auto">forked by {f.forked_by}</span>}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Branch protections */}
+      <div className="space-y-3">
+        <h2 className="font-heading text-[15px] font-bold text-foreground flex items-center gap-2"><Shield className="size-4" /> Branch protection rules</h2>
+        {protects.length > 0 && (
+          <div className="rounded-md border border-border overflow-hidden mb-3">
+            {protects.map((p) => (
+              <div className="flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0" key={p.id}>
+                <Shield className="size-4 text-primary shrink-0" />
+                <span className="font-heading text-[13px] font-semibold text-foreground">{p.pattern}</span>
+                {p.require_pull_request && <span className="font-mono text-[10px] text-muted-foreground">requires PR</span>}
+                <span className="font-mono text-[10px] text-muted-foreground">{p.required_approvals > 0 ? `${p.required_approvals} approval(s)` : ""}</span>
+                <Button className="size-7 text-destructive hover:text-destructive ml-auto" onClick={() => deleteProtect.mutate(p.id)} size="icon" variant="ghost">
+                  <Trash2 className="size-3.5" />
+                </Button>
+              </div>
+            ))}
+          </div>
+        )}
+        <div className="flex items-center gap-2">
+          <Input className="h-9 text-[13px] flex-1" placeholder="Branch pattern (e.g. main, release/*)" value={newProtectPattern} onChange={(e) => setNewProtectPattern(e.target.value)} />
+          <Button className="h-9 px-3 text-[13px]" disabled={!newProtectPattern.trim()} onClick={() => { createProtect.mutate(newProtectPattern.trim()); setNewProtectPattern(""); }}>Add rule</Button>
+        </div>
+      </div>
+
+      {/* Danger Zone */}
+      <div className="space-y-3 rounded-md border border-red-900/30 p-4">
+        <h2 className="font-heading text-[15px] font-bold text-red-600 flex items-center gap-2"><Trash2 className="size-4" /> Danger Zone</h2>
+        <div className="flex items-center justify-between">
+          <div>
+            <p className="text-[13px] font-medium text-foreground">Transfer ownership</p>
+            <p className="text-[11px] text-muted-foreground">Move this repository to another workspace.</p>
+          </div>
+          <div className="flex items-center gap-2">
+            <Input className="h-8 w-44 text-[12px]" placeholder="Target workspace" value={transferTarget} onChange={(e) => setTransferTarget(e.target.value)} />
+            <Button className="h-8 px-3 text-[12px]" disabled={!transferTarget.trim() || transferRepo.isPending} onClick={() => { if (confirm(`Transfer to ${transferTarget}?`)) transferRepo.mutate(); }} variant="outline">
+              <ArrowRight className="size-3 mr-1" /> Transfer
+            </Button>
+          </div>
+        </div>
+        <div className="flex items-center justify-between pt-2 border-t border-red-900/30">
+          <div>
+            <p className="text-[13px] font-medium text-foreground">Delete this repository</p>
+            <p className="text-[11px] text-muted-foreground">Once deleted, it cannot be recovered.</p>
+          </div>
+          <Button className="h-8 px-3 text-[12px]" disabled={deleteRepo.isPending} onClick={() => { if (confirm(`Permanently delete "${repoName}"? This cannot be undone.`)) deleteRepo.mutate(); }} variant="outline">
+            <Trash2 className="size-3 mr-1" /> Delete
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/tags.tsx b/src/page/workspace/repo/tags.tsx
new file mode 100644
index 0000000..f278b9a
--- /dev/null
+++ b/src/page/workspace/repo/tags.tsx
@@ -0,0 +1,106 @@
+import { useState } from "react";
+import { useParams, useSearchParams } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Tag, Plus, Trash2 } from "lucide-react";
+import PaginationBar from "./pagination";
+
+const LIMIT = 20;
+
+export default function TagsTab() {
+  const { projectName = "", repoName = "" } = useParams();
+  const qc = useQueryClient();
+  const [tagsSearchParams, setTagsSearchParams] = useSearchParams();
+  const offset = Number(tagsSearchParams.get("offset") ?? "0");
+  const setOffset = (n: number) => {
+    const next = new URLSearchParams(tagsSearchParams);
+    if (n <= 0) next.delete("offset"); else next.set("offset", String(n));
+    setTagsSearchParams(next, { replace: true });
+  };
+  const [newName, setNewName] = useState("");
+  const [newOid, setNewOid] = useState("");
+  const [newMessage, setNewMessage] = useState("");
+  const [showCreate, setShowCreate] = useState(false);
+
+  const { data: tags = [], isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "tags", offset],
+    queryFn: async () => {
+      const res = await client.gitListTags(projectName, repoName, { params: { offset, limit: LIMIT } } as any);
+      return (res.data as any).tags ?? [];
+    },
+    enabled: Boolean(projectName) && Boolean(repoName),
+    retry: false,
+  });
+
+  const createTag = useMutation({
+    mutationFn: async () => {
+      await client.gitInitTag(projectName, repoName, { name: newName, oid: newOid || undefined, message: newMessage || undefined } as any);
+    },
+    onSuccess: () => { setShowCreate(false); setNewName(""); setNewOid(""); setNewMessage(""); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "tags"] }); },
+  });
+
+  const deleteTag = useMutation({
+    mutationFn: async (name: string) => { await client.gitDeleteTag(projectName, repoName, { name } as any); },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "tags"] }),
+  });
+
+  const sorted = [...tags].sort((a, b) => a.name.localeCompare(b.name));
+
+  return (
+    <div className="space-y-5">
+      <div className="flex items-center justify-between">
+        <p className="font-mono text-[11px] text-muted-foreground">{tags.length} tag{tags.length !== 1 ? "s" : ""}</p>
+        <Button className="h-8 px-3 text-[12px]" onClick={() => setShowCreate(!showCreate)}>
+          <Plus className="size-3.5 mr-1" /> New tag
+        </Button>
+      </div>
+
+      {showCreate && (
+        <div className="rounded-md border border-border p-4 space-y-3">
+          <Input className="h-9 text-[13px]" placeholder="Tag name (e.g. v1.0.0)" value={newName} onChange={(e) => setNewName(e.target.value)} />
+          <Input className="h-9 text-[13px]" placeholder="Target commit OID (optional, defaults to HEAD)" value={newOid} onChange={(e) => setNewOid(e.target.value)} />
+          <Input className="h-9 text-[13px]" placeholder="Tag message (optional)" value={newMessage} onChange={(e) => setNewMessage(e.target.value)} />
+          <div className="flex gap-2">
+            <Button className="h-8 px-3 text-[12px]" disabled={!newName.trim() || createTag.isPending} onClick={() => createTag.mutate()}>
+              {createTag.isPending ? "Creating..." : "Create tag"}
+            </Button>
+            <Button className="h-8 px-3 text-[12px]" onClick={() => setShowCreate(false)} variant="outline">Cancel</Button>
+          </div>
+        </div>
+      )}
+
+      <div className="rounded-md border border-border overflow-hidden">
+        {isLoading ? (
+          <div className="px-4 py-2">{Array.from({ length: 3 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}</div>
+        ) : sorted.length > 0 ? (
+          <>
+          <div>
+            {sorted.map((tag) => (
+              <div className="flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0 transition-colors hover:bg-muted/40" key={tag.name}>
+                <Tag className="size-4 text-muted-foreground shrink-0" />
+                <span className="font-heading text-[13px] font-semibold text-foreground">{tag.name}</span>
+                {tag.is_annotated && <span className="rounded-sm border border-border px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground">annotated</span>}
+                <div className="ml-auto flex items-center gap-2">
+                  <code className="font-mono text-[10px] text-muted-foreground/60">{tag.oid.slice(0, 7)}</code>
+                  {tag.tagger && <span className="font-mono text-[11px] text-muted-foreground">{tag.tagger}</span>}
+                  <Button className="size-7 text-destructive hover:text-destructive" onClick={() => { if (confirm(`Delete tag "${tag.name}"?`)) deleteTag.mutate(tag.name); }} size="icon" variant="ghost">
+                    <Trash2 className="size-3.5" />
+                  </Button>
+                </div>
+              </div>
+            ))}
+          </div>
+              <PaginationBar offset={offset} limit={LIMIT} hasMore={tags.length >= LIMIT} onPrev={() => setOffset(Math.max(0, offset - LIMIT))} onNext={() => setOffset(offset + LIMIT)} />
+            </>
+        ) : (
+          <div className="py-12 text-center">
+            <Tag className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-2 text-[13px] text-muted-foreground">No tags yet</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repo/webhooks.tsx b/src/page/workspace/repo/webhooks.tsx
new file mode 100644
index 0000000..8485ac9
--- /dev/null
+++ b/src/page/workspace/repo/webhooks.tsx
@@ -0,0 +1,164 @@
+import { useState } from "react";
+import { useParams } from "react-router";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Trash2, Plus, Webhook, Pencil, History, X } from "lucide-react";
+
+const EVENT_OPTIONS = [
+  "push", "pull_request", "issues", "issue_comment", "pull_request_comment",
+  "create", "delete", "release", "fork", "star", "watch",
+];
+
+function formatDate(date: string) {
+  return new Date(date).toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
+
+export default function WebhooksTab() {
+  const { projectName = "", repoName = "" } = useParams();
+  const qc = useQueryClient();
+  const [showForm, setShowForm] = useState(false);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [url, setUrl] = useState("");
+  const [secret, setSecret] = useState("");
+  const [events, setEvents] = useState<string[]>(["push"]);
+  const [active, setActive] = useState(true);
+  const [error, setError] = useState("");
+  const [showDeliveries, setShowDeliveries] = useState<string | null>(null);
+
+  const { data: webhooks = [], isLoading } = useQuery({
+    queryKey: ["repo", projectName, repoName, "webhooks"],
+    queryFn: async () => {
+      const res = await client.gitListWebhooks(projectName, repoName);
+      return res.data;
+    },
+    enabled: Boolean(projectName) && Boolean(repoName), retry: false,
+  });
+
+  const { data: deliveries = [] } = useQuery({
+    queryKey: ["repo", projectName, repoName, "webhooks", "deliveries", showDeliveries],
+    queryFn: async () => {
+      const res = await client.gitListDeliveries(projectName, repoName, showDeliveries!);
+      return res.data;
+    },
+    enabled: Boolean(showDeliveries), retry: false,
+  });
+
+  const createWebhook = useMutation({
+    mutationFn: async () => { await client.gitCreateWebhook(projectName, repoName, { url, secret: secret || null, events, active }); },
+    onSuccess: () => { resetForm(); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "webhooks"] }); },
+    onError: (err: Error) => setError(err.message),
+  });
+
+  const updateWebhook = useMutation({
+    mutationFn: async (id: string) => { await client.gitUpdateWebhook!(projectName, repoName, id, { url, secret: secret || null, events, active }); },
+    onSuccess: () => { resetForm(); qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "webhooks"] }); },
+    onError: (err: Error) => setError(err.message),
+  });
+
+  const deleteWebhook = useMutation({
+    mutationFn: async (id: string) => { await client.gitDeleteWebhook(projectName, repoName, id); },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["repo", projectName, repoName, "webhooks"] }),
+  });
+
+  const resetForm = () => { setShowForm(false); setEditingId(null); setUrl(""); setSecret(""); setEvents(["push"]); setActive(true); setError(""); };
+
+  const startEdit = (wh: any) => { setEditingId(wh.id); setUrl(wh.url); setSecret(""); setEvents(wh.events); setActive(wh.active); setShowForm(true); };
+
+  const toggleEvent = (event: string) => { setEvents((prev) => prev.includes(event) ? prev.filter((e) => e !== event) : [...prev, event]); };
+
+  return (
+    <div className="space-y-5">
+      <div className="flex items-center justify-between">
+        <p className="font-mono text-[11px] text-muted-foreground">{webhooks.length} webhook{webhooks.length !== 1 ? "s" : ""}</p>
+        <Button className="h-8 px-3 text-[12px]" onClick={() => { resetForm(); setShowForm(!showForm); }}>
+          <Plus className="size-3.5 mr-1" /> Add webhook
+        </Button>
+      </div>
+
+      {showForm && (
+        <div className="rounded-md border border-border p-4 space-y-4">
+          <div className="flex items-center justify-between">
+            <span className="font-heading text-[13px] font-semibold text-foreground">{editingId ? "Edit webhook" : "New webhook"}</span>
+            <Button className="size-6 text-muted-foreground" onClick={resetForm} size="icon" variant="ghost"><X className="size-3" /></Button>
+          </div>
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Payload URL</label>
+            <Input className="mt-1 h-9 text-[13px]" placeholder="https://example.com/webhook" value={url} onChange={(e) => setUrl(e.target.value)} />
+          </div>
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Secret <span className="text-muted-foreground">(optional)</span></label>
+            <Input className="mt-1 h-9 text-[13px]" placeholder="A secret to sign the payload" value={secret} onChange={(e) => setSecret(e.target.value)} />
+          </div>
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Events</label>
+            <div className="mt-1.5 flex flex-wrap gap-1.5">
+              {EVENT_OPTIONS.map((event) => (
+                <button className={`px-2 py-1 text-[11px] font-mono rounded-sm border transition-colors ${events.includes(event) ? "border-primary bg-primary/5 text-primary" : "border-border text-muted-foreground hover:text-foreground"}`} key={event} onClick={() => toggleEvent(event)} type="button">
+                  {event}
+                </button>
+              ))}
+            </div>
+          </div>
+          <label className="flex items-center gap-2 cursor-pointer">
+            <input checked={active} className="size-3.5 rounded border-border accent-primary" onChange={(e) => setActive(e.target.checked)} type="checkbox" />
+            <span className="text-[13px] text-foreground">Active</span>
+          </label>
+          {error && <p className="text-[12px] text-destructive">{error}</p>}
+          <div className="flex items-center gap-2">
+            <Button className="h-8 px-3 text-[12px]" disabled={!url.trim() || (editingId ? updateWebhook.isPending : createWebhook.isPending)} onClick={() => { if (editingId) updateWebhook.mutate(editingId); else createWebhook.mutate(); }}>
+              {editingId ? "Update" : "Create"} webhook
+            </Button>
+            <Button className="h-8 px-3 text-[12px]" onClick={resetForm} variant="outline">Cancel</Button>
+          </div>
+        </div>
+      )}
+
+      <div className="rounded-md border border-border overflow-hidden">
+        {isLoading ? (
+          <div className="px-4 py-2">{Array.from({ length: 2 }).map((_, i) => <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />)}</div>
+        ) : webhooks.length > 0 ? (
+          webhooks.map((wh) => (
+            <div key={wh.id}>
+              <div className="flex items-center gap-3 border-b border-border px-4 py-3">
+                <Webhook className="size-4 text-muted-foreground shrink-0" />
+                <div className="min-w-0 flex-1">
+                  <span className="font-heading text-[13px] font-semibold text-foreground truncate block">{wh.url}</span>
+                  <div className="flex items-center gap-2 mt-0.5">
+                    <span className={`inline-block size-1.5 rounded-full ${wh.active ? "bg-green-500" : "bg-muted-foreground"}`} />
+                    <span className="font-mono text-[10px] text-muted-foreground">{wh.events.join(", ")}</span>
+                    <span className="font-mono text-[10px] text-muted-foreground">· {formatDate(wh.created_at)}</span>
+                  </div>
+                </div>
+                <Button className="size-7 text-muted-foreground hover:text-foreground" onClick={() => startEdit(wh)} size="icon" variant="ghost"><Pencil className="size-3" /></Button>
+                <Button className="size-7 text-muted-foreground hover:text-foreground" onClick={() => setShowDeliveries(showDeliveries === wh.id ? null : wh.id)} size="icon" variant="ghost"><History className="size-3" /></Button>
+                <Button className="size-7 text-destructive hover:text-destructive" onClick={() => deleteWebhook.mutate(wh.id)} size="icon" variant="ghost"><Trash2 className="size-3.5" /></Button>
+              </div>
+              {showDeliveries === wh.id && (
+                <div className="border-b border-border bg-muted/20 px-6 py-3">
+                  <p className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground mb-2">Delivery history</p>
+                  {deliveries.length > 0 ? (
+                    <div className="space-y-1">{deliveries.slice(0, 10).map((d: any, i: number) => (
+                      <div className="flex items-center gap-2 text-[11px] font-mono text-muted-foreground" key={i}>
+                        <span className={`inline-block size-1.5 rounded-full ${d.status === "success" ? "bg-green-500" : "bg-red-500"}`} />
+                        <span>{d.status ?? d.response_status ?? "?"}</span>
+                        {d.timestamp && <span>{formatDate(d.timestamp)}</span>}
+                        {d.http_status && <span>HTTP {d.http_status}</span>}
+                      </div>
+                    ))}</div>
+                  ) : <p className="text-[11px] text-muted-foreground">No deliveries yet</p>}
+                </div>
+              )}
+            </div>
+          ))
+        ) : (
+          <div className="py-8 text-center">
+            <Webhook className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-2 text-[13px] text-muted-foreground">No webhooks configured</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/repositories.tsx b/src/page/workspace/repositories.tsx
new file mode 100644
index 0000000..dbb44f0
--- /dev/null
+++ b/src/page/workspace/repositories.tsx
@@ -0,0 +1,437 @@
+import { useState, type FormEvent } from "react";
+import { Link, useParams } from "react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { client, type RepoResponse } from "@/client";
+import {
+  FolderPlus,
+  GitFork,
+  Plus,
+  Search,
+  Lock,
+  Globe,
+  Archive,
+  Check,
+  Download,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { cn } from "@/lib/utils";
+
+function formatSize(bytes: number) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatDate(date: string) {
+  const now = new Date();
+  const d = new Date(date);
+  const diff = now.getTime() - d.getTime();
+  const days = Math.floor(diff / 86400000);
+  if (days < 1) return "today";
+  if (days === 1) return "1 day ago";
+  if (days < 30) return `${days} days ago`;
+  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
+  return `${Math.floor(days / 365)}y ago`;
+}
+
+function VisibilityTag({ visibility }: { visibility: string }) {
+  if (visibility === "private") {
+    return (
+      <span className="inline-flex items-center gap-1 text-[11px] text-muted-foreground">
+        <Lock className="size-3" />Private
+      </span>
+    );
+  }
+  return (
+    <span className="inline-flex items-center gap-1 text-[11px] text-muted-foreground">
+      <Globe className="size-3" />Public
+    </span>
+  );
+}
+
+function RepoRow({ repo, projectName }: { repo: RepoResponse; projectName: string }) {
+  return (
+    <Link
+      className="group flex items-center gap-3 border-b border-border px-4 py-2.5 last:border-b-0 transition-colors hover:bg-muted/40"
+      to={`/${projectName}/repo/${repo.name}`}
+    >
+      <GitFork className="size-4 text-muted-foreground shrink-0" />
+      <div className="min-w-0 flex-1">
+        <div className="flex items-baseline gap-1.5 flex-wrap">
+          <span className="font-heading text-[13px] font-semibold text-foreground">{repo.name}</span>
+          {repo.is_archived && (
+            <span className="inline-flex items-center gap-1 text-[11px] text-muted-foreground">
+              <Archive className="size-3" />Archived
+            </span>
+          )}
+          <VisibilityTag visibility={repo.visibility} />
+        </div>
+        {repo.description && (
+          <p className="text-[11px] text-muted-foreground truncate mt-0.5">{repo.description}</p>
+        )}
+      </div>
+      <div className="shrink-0 flex items-center gap-4 font-mono text-[11px] text-muted-foreground">
+        <span>{formatSize(repo.size_bytes)}</span>
+        <span>{formatDate(repo.updated_at)}</span>
+      </div>
+    </Link>
+  );
+}
+
+function RepoListView({
+  projectName,
+  onCreate,
+}: {
+  projectName: string;
+  onCreate: () => void;
+}) {
+  const [search, setSearch] = useState("");
+
+  const { data: repos = [], isLoading } = useQuery({
+    queryKey: ["repos", projectName, search],
+    queryFn: async () => {
+      const res = await client.gitListRepos(projectName, { search: search || undefined });
+      return res.data;
+    },
+    retry: false,
+  });
+
+  return (
+    <>
+      <div className="flex items-center justify-between">
+        <h1 className="font-heading text-lg font-bold text-foreground">Repositories</h1>
+        <Button className="h-8 rounded px-3 text-[13px]" onClick={onCreate}>
+          <Plus className="size-3.5 mr-1" />
+          New repo
+        </Button>
+      </div>
+
+      <div className="mt-6 rounded-md border border-border overflow-hidden">
+        <div className="flex items-center gap-2 bg-muted/50 px-3 py-2 border-b border-border">
+          <span className="font-mono text-[11px] text-muted-foreground">{repos.length} repositories</span>
+          <div className="ml-auto relative">
+            <Search className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+            <Input
+              className="h-7 w-52 rounded-sm border-border bg-card pl-7 text-[12px]"
+              placeholder="Filter repos..."
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+            />
+          </div>
+        </div>
+
+        {isLoading ? (
+          <div className="px-4 py-2">
+            {Array.from({ length: 3 }).map((_, i) => (
+              <div className="h-6 animate-pulse rounded bg-muted/50 my-1.5" key={i} />
+            ))}
+          </div>
+        ) : repos.length > 0 ? (
+          <div>
+            {repos.map((repo) => (
+              <RepoRow key={repo.id} projectName={projectName} repo={repo} />
+            ))}
+          </div>
+        ) : (
+          <div className="py-12 text-center">
+            <FolderPlus className="mx-auto size-5 text-muted-foreground/20" />
+            <p className="mt-3 text-[13px] text-muted-foreground">No repositories yet</p>
+          </div>
+        )}
+      </div>
+    </>
+  );
+}
+
+type RepoCreateMode = "create" | "clone";
+
+function RepoCreateView({
+  projectName,
+  onCancel,
+}: {
+  projectName: string;
+  onCancel: () => void;
+}) {
+  const qc = useQueryClient();
+  const [mode, setMode] = useState<RepoCreateMode>("create");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  // Shared
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [visibility, setVisibility] = useState("private");
+
+  // Create-only
+  const [defaultBranch, setDefaultBranch] = useState("main");
+  const [initReadme, setInitReadme] = useState(true);
+  const [enableLfs, setEnableLfs] = useState(false);
+
+  // Clone-only
+  const [sourceUrl, setSourceUrl] = useState("");
+
+  const handleCreate = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    if (!name.trim()) {
+      setError("Name is required.");
+      setSubmitting(false);
+      return;
+    }
+
+    try {
+      await client.gitCreateRepo(projectName, {
+        name: name.trim(),
+        description: description || null,
+        visibility,
+        default_branch: defaultBranch || null,
+        initialize_with_readme: initReadme,
+        enable_lfs: enableLfs,
+      });
+      await qc.invalidateQueries({ queryKey: ["repos", projectName] });
+      onCancel();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to create repository.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleClone = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    if (!name.trim()) {
+      setError("Name is required.");
+      setSubmitting(false);
+      return;
+    }
+    if (!sourceUrl.trim()) {
+      setError("Source URL is required.");
+      setSubmitting(false);
+      return;
+    }
+
+    try {
+      await client.gitCloneRepo(projectName, {
+        name: name.trim(),
+        source_url: sourceUrl.trim(),
+        description: description || null,
+        visibility,
+      });
+      await qc.invalidateQueries({ queryKey: ["repos", projectName] });
+      onCancel();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to clone repository.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleSubmit = mode === "create" ? handleCreate : handleClone;
+
+  const modeTabs: { key: RepoCreateMode; label: string; icon: React.ReactNode }[] = [
+    { key: "create", label: "New", icon: <Plus className="size-3.5" /> },
+    { key: "clone", label: "Clone", icon: <Download className="size-3.5" /> },
+  ];
+
+  return (
+    <div className="max-w-2xl">
+      <h1 className="font-heading text-lg font-bold text-foreground">
+        Create a new repository
+      </h1>
+      <p className="mt-1 text-[13px] text-muted-foreground">
+        A repository contains all project files, including the revision history.
+      </p>
+
+      {/* Mode tabs */}
+      <div className="mt-5 flex gap-1 rounded-lg bg-muted/50 p-1">
+        {modeTabs.map((tab) => (
+          <button
+            className={cn(
+              "flex flex-1 items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-[13px] font-medium transition-colors",
+              mode === tab.key
+                ? "bg-background text-foreground shadow-sm"
+                : "text-muted-foreground hover:text-foreground",
+            )}
+            key={tab.key}
+            onClick={() => { setMode(tab.key); setError(""); }}
+            type="button"
+          >
+            {tab.icon}
+            {tab.label}
+          </button>
+        ))}
+      </div>
+
+      <form className="mt-5 space-y-5" onSubmit={(e) => { e.preventDefault(); void handleSubmit(e); }}>
+        {/* Source URL — clone only */}
+        {mode === "clone" && (
+          <div>
+            <label className="text-[13px] font-medium text-foreground">Clone URL</label>
+            <Input
+              className="mt-1.5 h-9 text-[13px] font-mono"
+              name="source_url"
+              onChange={(e) => setSourceUrl(e.target.value)}
+              placeholder="https://github.com/user/repo.git"
+              required
+              autoFocus
+              value={sourceUrl}
+            />
+            <p className="mt-1 text-[11px] text-muted-foreground">
+              The remote Git URL to clone from. Supports HTTPS and SSH.
+            </p>
+          </div>
+        )}
+
+        {/* Name */}
+        <div>
+          <label className="text-[13px] font-medium text-foreground">Repository name</label>
+          <Input
+            className="mt-1.5 h-9 text-[13px]"
+            name="name"
+            onChange={(e) => setName(e.target.value)}
+            placeholder="e.g. my-project"
+            required
+            autoFocus={mode !== "clone"}
+            value={name}
+          />
+          <p className="mt-1 text-[11px] text-muted-foreground">
+            Great repository names are short and memorable.
+          </p>
+        </div>
+
+        {/* Description */}
+        <div>
+          <label className="text-[13px] font-medium text-foreground">
+            Description <span className="text-muted-foreground">(optional)</span>
+          </label>
+          <Textarea
+            className="mt-1.5 min-h-[72px] text-[13px]"
+            name="description"
+            onChange={(e) => setDescription(e.target.value)}
+            placeholder="A brief description of the repository"
+            value={description}
+          />
+        </div>
+
+        {/* Visibility */}
+        <div>
+          <label className="text-[13px] font-medium text-foreground">Visibility</label>
+          <div className="mt-1.5 flex gap-2">
+            {[
+              { value: "private", icon: <Lock className="size-3.5" />, label: "Private", desc: "Only members can see this repository" },
+              { value: "public", icon: <Globe className="size-3.5" />, label: "Public", desc: "Anyone can see this repository" },
+            ].map((opt) => (
+              <button
+                className={cn(
+                  "flex items-start gap-2 rounded-md border p-3 text-left transition-colors",
+                  visibility === opt.value
+                    ? "border-primary bg-primary/5"
+                    : "border-border hover:border-muted-foreground/30",
+                )}
+                key={opt.value}
+                onClick={() => setVisibility(opt.value)}
+                type="button"
+              >
+                <span className={cn("mt-0.5", visibility === opt.value ? "text-primary" : "text-muted-foreground")}>
+                  {opt.icon}
+                </span>
+                <div>
+                  <span className={cn("text-[13px] font-medium", visibility === opt.value ? "text-foreground" : "text-muted-foreground")}>
+                    {opt.label}
+                  </span>
+                  <p className="text-[11px] text-muted-foreground">{opt.desc}</p>
+                </div>
+                {visibility === opt.value && (
+                  <Check className="size-3.5 text-primary shrink-0 mt-0.5 ml-auto" />
+                )}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Create-only fields */}
+        {mode === "create" && (
+          <>
+            {/* Default branch */}
+            <div>
+              <label className="text-[13px] font-medium text-foreground">Default branch</label>
+              <Input
+                className="mt-1.5 h-9 w-48 text-[13px]"
+                name="default_branch"
+                onChange={(e) => setDefaultBranch(e.target.value)}
+                value={defaultBranch}
+              />
+            </div>
+
+            {/* Initialize */}
+            <div>
+              <label className="text-[13px] font-medium text-foreground">Initialize this repository</label>
+              <div className="mt-2 space-y-2">
+                <label className="flex items-center gap-2 cursor-pointer">
+                  <input
+                    checked={initReadme}
+                    className="size-3.5 rounded border-border accent-primary"
+                    onChange={(e) => setInitReadme(e.target.checked)}
+                    type="checkbox"
+                  />
+                  <span className="text-[13px] text-foreground">Add a README file</span>
+                </label>
+                <label className="flex items-center gap-2 cursor-pointer">
+                  <input
+                    checked={enableLfs}
+                    className="size-3.5 rounded border-border accent-primary"
+                    onChange={(e) => setEnableLfs(e.target.checked)}
+                    type="checkbox"
+                  />
+                  <span className="text-[13px] text-foreground">Enable Git LFS</span>
+                </label>
+              </div>
+            </div>
+          </>
+        )}
+
+        {error && (
+          <p className="rounded-md bg-destructive/5 px-3 py-2 text-[12px] text-destructive">{error}</p>
+        )}
+
+        {/* Actions */}
+        <div className="flex items-center gap-3 pt-2">
+          <Button className="h-9 px-4 text-[13px]" disabled={submitting} type="submit">
+            {submitting
+              ? mode === "create"
+                ? "Creating..."
+                : "Cloning..."
+              : mode === "create"
+                ? "Create repository"
+                : "Clone repository"}
+          </Button>
+          <Button className="h-9 px-4 text-[13px]" onClick={onCancel} variant="outline">
+            Cancel
+          </Button>
+        </div>
+      </form>
+    </div>
+  );
+}
+
+export default function WorkspaceRepositoriesPage() {
+  const { projectName = "" } = useParams();
+  const [mode, setMode] = useState<"list" | "create">("list");
+
+  return (
+    <div className="px-8 py-10">
+      {mode === "list" ? (
+        <RepoListView projectName={projectName} onCreate={() => setMode("create")} />
+      ) : (
+        <RepoCreateView projectName={projectName} onCancel={() => setMode("list")} />
+      )}
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/page/workspace/settings/general.tsx b/src/page/workspace/settings/general.tsx
new file mode 100644
index 0000000..c422299
--- /dev/null
+++ b/src/page/workspace/settings/general.tsx
@@ -0,0 +1,121 @@
+import { useState, useId, type FormEvent } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import AvatarUploader from "@/components/ui/avatar-uploader";
+
+function SettingsSkeleton({ rows = 3 }: { rows?: number }) {
+  return (
+    <div className="space-y-4" aria-busy="true" aria-label="Loading settings">
+      {Array.from({ length: rows }).map((_, i) => (
+        <div className="h-9 animate-pulse rounded-lg bg-muted/50" key={i} />
+      ))}
+    </div>
+  );
+}
+
+export default function GeneralTab({ projectName }: { projectName: string }) {
+  const qc = useQueryClient();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+  const nameId = useId();
+  const descId = useId();
+  const avatarId = useId();
+
+  const { data: workspace, isLoading } = useQuery({
+    queryKey: ["workspace", projectName],
+    queryFn: async () => {
+      const res = await client.workspaceGetWorkspace(projectName);
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+    const name = (form.get("name") as string) || null;
+    const description = (form.get("description") as string) || null;
+    const avatarUrl = (form.get("avatar_url") as string) || null;
+
+    try {
+      await client.workspaceUpdateWorkspace(projectName, {
+        name,
+        description,
+        avatar_url: avatarUrl,
+      });
+      await qc.invalidateQueries({ queryKey: ["workspace", projectName] });
+      await qc.invalidateQueries({ queryKey: ["workspace", "my"] });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to update workspace.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (isLoading) return <SettingsSkeleton />;
+
+  return (
+    <form className="max-w-2xl space-y-8" onSubmit={(e) => void handleSubmit(e)}>
+      {/* Identity card */}
+      <div className="rounded-xl border border-border bg-card p-6 space-y-5">
+        <div>
+          <h2 className="text-sm font-semibold text-foreground mb-1">Workspace identity</h2>
+          <p className="text-xs text-muted-foreground">These details identify your workspace across the platform.</p>
+        </div>
+
+        <div className="space-y-4">
+          <div>
+            <label className="text-sm font-medium text-foreground" htmlFor={nameId}>Name</label>
+            <Input className="mt-2 h-10 text-sm" defaultValue={workspace?.name ?? ""} id={nameId} name="name" />
+            <p className="mt-1.5 text-xs text-muted-foreground">Changing the name will also change the workspace URL.</p>
+          </div>
+
+          <div>
+            <label className="text-sm font-medium text-foreground" htmlFor={descId}>
+              Description <span className="font-normal text-muted-foreground">— optional</span>
+            </label>
+            <Textarea
+              className="mt-2 min-h-[80px] text-sm"
+              defaultValue={workspace?.description ?? ""}
+              id={descId}
+              name="description"
+              placeholder="A brief description of the workspace"
+            />
+          </div>
+
+          <div>
+            <label className="text-sm font-medium text-foreground" htmlFor={avatarId}>
+              Avatar <span className="font-normal text-muted-foreground">— optional</span>
+            </label>
+            <div className="mt-2">
+              <AvatarUploader
+                currentUrl={workspace?.avatar_url}
+                label="Workspace avatar"
+                onUploaded={() => {
+                  qc.invalidateQueries({ queryKey: ["workspace", projectName] });
+                  qc.invalidateQueries({ queryKey: ["workspace", "my"] });
+                }}
+                uploadEndpoint={`/api/v1/workspace/${projectName}/avatar`}
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {error && <p className="text-sm text-destructive bg-destructive/10 rounded-lg px-4 py-3" role="alert">{error}</p>}
+
+      <div className="flex items-center gap-3">
+        <Button className="h-10 px-5 text-sm" disabled={submitting} type="submit">
+          {submitting ? "Saving..." : "Save changes"}
+        </Button>
+        {submitting && <span className="text-xs text-muted-foreground">Updating workspace...</span>}
+      </div>
+    </form>
+  );
+}
diff --git a/src/page/workspace/settings/groups.tsx b/src/page/workspace/settings/groups.tsx
new file mode 100644
index 0000000..25907ea
--- /dev/null
+++ b/src/page/workspace/settings/groups.tsx
@@ -0,0 +1,153 @@
+import { memo, useState, useId } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type WorkspaceGroupResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import { Plus, Trash2 } from "lucide-react";
+
+const GroupRow = memo(function GroupRow({
+  group,
+  onRemove,
+}: {
+  group: WorkspaceGroupResponse;
+  onRemove: (name: string) => void;
+}) {
+  return (
+    <div className="flex items-center gap-3 border-b border-border/60 px-5 py-3 last:border-b-0 transition-colors hover:bg-muted/30">
+      <span
+        aria-hidden="true"
+        className={cn(
+          "grid size-7 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-xs font-bold text-white",
+          workspaceColor(group.name),
+        )}
+      >
+        {group.avatar_url ? (
+          <img alt="" className="size-full object-cover" src={group.avatar_url} />
+        ) : (
+          workspaceInitial(group.name)
+        )}
+      </span>
+      <span className="text-sm font-medium text-foreground">{group.name}</span>
+      {group.is_deleted && (
+        <span className="rounded bg-muted/60 px-2 py-0.5 text-[11px] text-muted-foreground">Deleted</span>
+      )}
+      <div className="ml-auto">
+        <Button
+          aria-label={`Delete group ${group.name}`}
+          className="size-8 text-muted-foreground hover:text-destructive"
+          onClick={() => onRemove(group.name)}
+          size="icon"
+          type="button"
+          variant="ghost"
+        >
+          <Trash2 aria-hidden="true" className="size-4" />
+        </Button>
+      </div>
+    </div>
+  );
+});
+
+function ListSkeleton() {
+  return (
+    <div aria-busy="true" className="px-5 py-3 space-y-3">
+      {Array.from({ length: 2 }).map((_, i) => (
+        <div className="h-8 animate-pulse rounded-lg bg-muted/50" key={i} />
+      ))}
+    </div>
+  );
+}
+
+export default function GroupsTab({ projectName }: { projectName: string }) {
+  const qc = useQueryClient();
+  const [newName, setNewName] = useState("");
+  const groupInputId = useId();
+
+  const { data: groups = [], isLoading } = useQuery({
+    queryKey: ["workspace", projectName, "groups"],
+    queryFn: async () => {
+      const res = await client.workspaceListGroups(projectName);
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const createGroup = useMutation({
+    mutationFn: async () => {
+      await client.workspaceCreateGroup(projectName, { name: newName.trim() });
+    },
+    onSuccess: () => {
+      setNewName("");
+      qc.invalidateQueries({ queryKey: ["workspace", projectName, "groups"] });
+    },
+  });
+
+  const deleteGroup = useMutation({
+    mutationFn: async (groupName: string) => {
+      await client.workspaceDeleteGroup(projectName, groupName);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["workspace", projectName, "groups"] }),
+  });
+
+  return (
+    <div className="max-w-2xl space-y-8">
+      {/* Create group card */}
+      <div className="rounded-xl border border-border bg-card p-6 space-y-4">
+        <div>
+          <h2 className="text-sm font-semibold text-foreground mb-1">Create a group</h2>
+          <p className="text-xs text-muted-foreground">Groups help organize members and manage permissions.</p>
+        </div>
+
+        <div className="flex items-center gap-3">
+          <Input
+            className="h-10 flex-1 text-sm"
+            id={groupInputId}
+            onChange={(e) => setNewName(e.target.value)}
+            placeholder="Group name"
+            value={newName}
+          />
+          <Button
+            className="h-10 px-4 text-sm"
+            disabled={!newName.trim()}
+            onClick={() => createGroup.mutate()}
+            type="button"
+          >
+            <Plus aria-hidden="true" className="mr-1.5 size-4" />
+            Create
+          </Button>
+        </div>
+      </div>
+
+      {/* Group list card */}
+      <div className="rounded-xl border border-border bg-card overflow-hidden">
+        <div className="border-b border-border px-5 py-3">
+          <h2 className="text-sm font-semibold text-foreground">
+            All groups
+            {groups.length > 0 && (
+              <span className="ml-2 font-normal text-muted-foreground">
+                ({groups.filter((g) => !g.is_deleted).length})
+              </span>
+            )}
+          </h2>
+        </div>
+
+        {isLoading ? (
+          <ListSkeleton />
+        ) : (() => {
+          const active = groups.filter((g) => !g.is_deleted);
+          return active.length > 0 ? (
+            active.map((g) => (
+              <GroupRow key={g.name} group={g} onRemove={(n) => deleteGroup.mutate(n)} />
+            ))
+          ) : (
+            <div className="py-16 text-center">
+              <p className="text-sm text-muted-foreground">No groups yet</p>
+              <p className="mt-1 text-xs text-muted-foreground/60">Create a group above to get started.</p>
+            </div>
+          );
+        })()}
+      </div>
+    </div>
+  );
+}
diff --git a/src/page/workspace/settings/index.tsx b/src/page/workspace/settings/index.tsx
new file mode 100644
index 0000000..bd24a12
--- /dev/null
+++ b/src/page/workspace/settings/index.tsx
@@ -0,0 +1,55 @@
+import { useParams } from "react-router";
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
+import GeneralTab from "./general";
+import MembersTab from "./members";
+import GroupsTab from "./groups";
+import JoinTab from "./join";
+
+const TABS = [
+  { value: "general", label: "General" },
+  { value: "members", label: "Members" },
+  { value: "groups", label: "Groups" },
+  { value: "join", label: "Join" },
+] as const;
+
+export default function WorkspaceSettingsPage() {
+  const { projectName = "" } = useParams();
+
+  return (
+    <div className="mx-auto max-w-4xl px-8 py-12">
+      <div className="mb-8">
+        <h1 className="text-xl font-bold tracking-tight text-foreground">Settings</h1>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Manage your workspace configuration and members.
+        </p>
+      </div>
+
+      <Tabs defaultValue="general">
+        <TabsList
+          aria-label="Settings sections"
+          className="mb-8 h-9 w-fit border-b border-border"
+          variant="line"
+        >
+          {TABS.map(({ value, label }) => (
+            <TabsTrigger className="px-3 text-[13px]" key={value} value={value}>
+              {label}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+
+        <TabsContent value="general">
+          <GeneralTab projectName={projectName} />
+        </TabsContent>
+        <TabsContent value="members">
+          <MembersTab projectName={projectName} />
+        </TabsContent>
+        <TabsContent value="groups">
+          <GroupsTab projectName={projectName} />
+        </TabsContent>
+        <TabsContent value="join">
+          <JoinTab projectName={projectName} />
+        </TabsContent>
+      </Tabs>
+    </div>
+  );
+}
diff --git a/src/page/workspace/settings/join.tsx b/src/page/workspace/settings/join.tsx
new file mode 100644
index 0000000..e372200
--- /dev/null
+++ b/src/page/workspace/settings/join.tsx
@@ -0,0 +1,241 @@
+import { useState, useId, type FormEvent } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Check, X } from "lucide-react";
+
+function FormSkeleton() {
+  return (
+    <div className="space-y-4" aria-busy="true">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div className="h-10 animate-pulse rounded-lg bg-muted/50" key={i} />
+      ))}
+    </div>
+  );
+}
+
+export default function JoinTab({ projectName }: { projectName: string }) {
+  const qc = useQueryClient();
+  const qId = useId();
+  const aId = useId();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState("");
+
+  const { data: strategy, isLoading } = useQuery({
+    queryKey: ["workspace", projectName, "join-strategy"],
+    queryFn: async () => {
+      const res = await client.workspaceJoinStrategy(projectName);
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const { data: applies = [], isLoading: loadingApplies } = useQuery({
+    queryKey: ["workspace", projectName, "join-applies"],
+    queryFn: async () => {
+      const res = await client.workspaceListJoinApplies(projectName, { status: "pending" });
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const [enabled, setEnabled] = useState(strategy?.enabled ?? false);
+  const [requireApproval, setRequireApproval] = useState(strategy?.require_approval ?? true);
+  const [requireQuestion, setRequireQuestion] = useState(strategy?.require_question ?? false);
+  const [question, setQuestion] = useState(strategy?.question ?? "");
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError("");
+    setSubmitting(true);
+
+    const form = new FormData(event.currentTarget);
+    const answer = (form.get("answer") as string) || null;
+
+    try {
+      await client.workspaceUpdateJoinStrategy(projectName, {
+        enabled,
+        require_approval: requireApproval,
+        require_question: requireQuestion,
+        question: requireQuestion ? question : null,
+        answer,
+      });
+      await qc.invalidateQueries({ queryKey: ["workspace", projectName, "join-strategy"] });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to update join strategy.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const approveApply = useMutation({
+    mutationFn: async ({ username, approved }: { username: string; approved: boolean }) => {
+      await client.workspaceApproveJoin(projectName, username, { approved, reason: null });
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["workspace", projectName, "join-applies"] }),
+  });
+
+  if (isLoading) return <FormSkeleton />;
+
+  return (
+    <div className="max-w-2xl space-y-8">
+      {/* Join strategy card */}
+      <div className="rounded-xl border border-border bg-card p-6">
+        <div className="mb-6">
+          <h2 className="text-sm font-semibold text-foreground mb-1">Join settings</h2>
+          <p className="text-xs text-muted-foreground">Control how users can join this workspace.</p>
+        </div>
+
+        <form className="space-y-6" onSubmit={(e) => void handleSubmit(e)}>
+          {/* Enable toggle */}
+          <label className="flex items-start gap-3 cursor-pointer">
+            <input
+              checked={enabled}
+              className="mt-0.5 size-4 rounded border-border accent-primary"
+              onChange={(e) => setEnabled(e.target.checked)}
+              type="checkbox"
+            />
+            <div>
+              <span className="text-sm font-medium text-foreground">Enable public join</span>
+              <p className="text-xs text-muted-foreground">When enabled, users can request to join this workspace.</p>
+            </div>
+          </label>
+
+          {enabled && (
+            <div className="space-y-5 border-t border-border pt-5">
+              {/* Require approval */}
+              <label className="flex items-start gap-3 cursor-pointer">
+                <input
+                  checked={requireApproval}
+                  className="mt-0.5 size-4 rounded border-border accent-primary"
+                  onChange={(e) => setRequireApproval(e.target.checked)}
+                  type="checkbox"
+                />
+                <div>
+                  <span className="text-sm font-medium text-foreground">Require admin approval</span>
+                  <p className="text-xs text-muted-foreground">Workspace admins must approve join requests.</p>
+                </div>
+              </label>
+
+              {/* Require question */}
+              <label className="flex items-start gap-3 cursor-pointer">
+                <input
+                  checked={requireQuestion}
+                  className="mt-0.5 size-4 rounded border-border accent-primary"
+                  onChange={(e) => setRequireQuestion(e.target.checked)}
+                  type="checkbox"
+                />
+                <div>
+                  <span className="text-sm font-medium text-foreground">Require answer to question</span>
+                  <p className="text-xs text-muted-foreground">Users must answer a question when requesting to join.</p>
+                </div>
+              </label>
+
+              {requireQuestion && (
+                <>
+                  <div>
+                    <label className="text-sm font-medium text-foreground" htmlFor={qId}>Question</label>
+                    <Input
+                      className="mt-2 h-10 text-sm"
+                      id={qId}
+                      name="question"
+                      onChange={(e) => setQuestion(e.target.value)}
+                      placeholder="e.g. Why do you want to join?"
+                      value={question}
+                    />
+                  </div>
+
+                  {strategy?.has_answer && (
+                    <div>
+                      <label className="text-sm font-medium text-foreground" htmlFor={aId}>
+                        Expected answer <span className="font-normal text-muted-foreground">— optional</span>
+                      </label>
+                      <Input
+                        className="mt-2 h-10 text-sm"
+                        id={aId}
+                        name="answer"
+                        placeholder="Answer that auto-approves requests"
+                      />
+                    </div>
+                  )}
+                </>
+              )}
+            </div>
+          )}
+
+          {error && <p className="text-sm text-destructive bg-destructive/10 rounded-lg px-4 py-3" role="alert">{error}</p>}
+
+          <Button className="h-10 px-5 text-sm" disabled={submitting} type="submit">
+            {submitting ? "Saving..." : "Save changes"}
+          </Button>
+        </form>
+      </div>
+
+      {/* Pending requests card */}
+      {enabled && requireApproval && (
+        <div className="rounded-xl border border-border bg-card overflow-hidden">
+          <div className="border-b border-border px-5 py-3">
+            <h2 className="text-sm font-semibold text-foreground">
+              Pending join requests
+              {applies.length > 0 && (
+                <span className="ml-2 font-normal text-muted-foreground">({applies.length})</span>
+              )}
+            </h2>
+          </div>
+
+          {loadingApplies ? (
+            <div className="px-5 py-3 space-y-3">
+              {Array.from({ length: 2 }).map((_, i) => (
+                <div className="h-10 animate-pulse rounded-lg bg-muted/50" key={i} />
+              ))}
+            </div>
+          ) : applies.length > 0 ? (
+            applies.map((apply) => (
+              <div
+                className="flex items-center gap-3 border-b border-border/60 px-5 py-3 last:border-b-0 transition-colors hover:bg-muted/30"
+                key={apply.username}
+              >
+                <div className="min-w-0 flex-1">
+                  <span className="text-sm font-medium text-foreground">{apply.username}</span>
+                  {apply.message && (
+                    <p className="mt-0.5 truncate text-xs text-muted-foreground">{apply.message}</p>
+                  )}
+                </div>
+                <span className="shrink-0 text-xs text-muted-foreground">
+                  {new Date(apply.created_at).toLocaleDateString("en-US", { month: "short", day: "numeric" })}
+                </span>
+                <div className="flex shrink-0 items-center gap-2">
+                  <Button
+                    aria-label={`Approve ${apply.username}`}
+                    className="h-8 px-3 text-xs"
+                    onClick={() => approveApply.mutate({ username: apply.username, approved: true })}
+                    size="sm"
+                    type="button"
+                  >
+                    <Check aria-hidden="true" className="mr-1 size-3.5" /> Approve
+                  </Button>
+                  <Button
+                    aria-label={`Reject ${apply.username}`}
+                    className="h-8 px-3 text-xs"
+                    onClick={() => approveApply.mutate({ username: apply.username, approved: false })}
+                    size="sm"
+                    type="button"
+                    variant="outline"
+                  >
+                    <X aria-hidden="true" className="mr-1 size-3.5" /> Reject
+                  </Button>
+                </div>
+              </div>
+            ))
+          ) : (
+            <div className="py-16 text-center">
+              <p className="text-sm text-muted-foreground">No pending requests</p>
+              <p className="mt-1 text-xs text-muted-foreground/60">New join requests will appear here.</p>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/page/workspace/settings/members.tsx b/src/page/workspace/settings/members.tsx
new file mode 100644
index 0000000..6c92ec7
--- /dev/null
+++ b/src/page/workspace/settings/members.tsx
@@ -0,0 +1,210 @@
+import { memo, useState, useId } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { client, type WorkspaceMemberResponse } from "@/client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { cn } from "@/lib/utils";
+import { workspaceColor, workspaceInitial } from "@/components/shell/shared";
+import { Trash2, UserPlus, Crown } from "lucide-react";
+
+const MemberRow = memo(function MemberRow({
+  member,
+  onRemove,
+  onUpdateRole,
+}: {
+  member: WorkspaceMemberResponse;
+  onRemove: (username: string) => void;
+  onUpdateRole: (username: string, admin: boolean) => void;
+}) {
+  const name = member.display_name ?? member.username;
+  return (
+    <div className="flex items-center gap-3 border-b border-border/60 px-5 py-3 last:border-b-0 transition-colors hover:bg-muted/30">
+      <span
+        aria-hidden="true"
+        className={cn(
+          "grid size-7 shrink-0 place-items-center overflow-hidden rounded-full bg-gradient-to-br text-xs font-bold text-white",
+          workspaceColor(name),
+        )}
+      >
+        {member.avatar_url ? (
+          <img alt="" className="size-full object-cover" src={member.avatar_url} />
+        ) : (
+          workspaceInitial(name)
+        )}
+      </span>
+
+      <div className="min-w-0 flex-1">
+        <div className="text-sm font-medium text-foreground">{member.display_name ?? member.username}</div>
+        <div className="text-xs text-muted-foreground">@{member.username}</div>
+      </div>
+
+      {member.owner ? (
+        <span className="inline-flex items-center gap-1.5 rounded bg-amber-500/10 px-2.5 py-1 text-[11px] font-medium text-amber-600 dark:text-amber-400">
+          <Crown className="size-3" /> Owner
+        </span>
+      ) : (
+        <div className="flex items-center gap-2">
+          <Select
+            aria-label={`Change role for ${member.username}`}
+            defaultValue={member.admin ? "admin" : "member"}
+            onValueChange={(v) => onUpdateRole(member.username, v === "admin")}
+          >
+            <SelectTrigger className="h-8 w-[100px] text-xs">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="admin">Admin</SelectItem>
+              <SelectItem value="member">Member</SelectItem>
+            </SelectContent>
+          </Select>
+          <Button
+            aria-label={`Remove ${member.username} from workspace`}
+            className="size-8 text-muted-foreground hover:text-destructive"
+            onClick={() => onRemove(member.username)}
+            size="icon"
+            type="button"
+            variant="ghost"
+          >
+            <Trash2 aria-hidden="true" className="size-4" />
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+});
+
+function ListSkeleton({ rows = 3 }: { rows?: number }) {
+  return (
+    <div aria-busy="true" className="px-5 py-3 space-y-3">
+      {Array.from({ length: rows }).map((_, i) => (
+        <div className="h-10 animate-pulse rounded-lg bg-muted/50" key={i} />
+      ))}
+    </div>
+  );
+}
+
+export default function MembersTab({ projectName }: { projectName: string }) {
+  const qc = useQueryClient();
+  const [addUsername, setAddUsername] = useState("");
+  const [addAdmin, setAddAdmin] = useState(false);
+  const userInputId = useId();
+
+  const { data: members = [], isLoading } = useQuery({
+    queryKey: ["workspace", projectName, "members"],
+    queryFn: async () => {
+      const res = await client.workspaceListMembers(projectName);
+      return res.data;
+    },
+    retry: false,
+  });
+
+  const addMember = useMutation({
+    mutationFn: async () => {
+      await client.workspaceAddMember(projectName, {
+        username: addUsername.trim(),
+        admin: addAdmin,
+      });
+    },
+    onSuccess: () => {
+      setAddUsername("");
+      setAddAdmin(false);
+      qc.invalidateQueries({ queryKey: ["workspace", projectName, "members"] });
+    },
+  });
+
+  const removeMember = useMutation({
+    mutationFn: async (username: string) => {
+      await client.workspaceRemoveMember(projectName, username);
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["workspace", projectName, "members"] }),
+  });
+
+  const updateMember = useMutation({
+    mutationFn: async ({ username, admin }: { username: string; admin: boolean }) => {
+      await client.workspaceUpdateMember(projectName, username, { admin });
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["workspace", projectName, "members"] }),
+  });
+
+  return (
+    <div className="max-w-2xl space-y-8">
+      {/* Add member card */}
+      <div className="rounded-xl border border-border bg-card p-6 space-y-4">
+        <div>
+          <h2 className="text-sm font-semibold text-foreground mb-1">Add a member</h2>
+          <p className="text-xs text-muted-foreground">Invite users to collaborate in this workspace.</p>
+        </div>
+
+        <div className="flex items-center gap-3">
+          <Input
+            className="h-10 flex-1 text-sm"
+            id={userInputId}
+            onChange={(e) => setAddUsername(e.target.value)}
+            placeholder="Username"
+            value={addUsername}
+          />
+          <label className="flex shrink-0 cursor-pointer items-center gap-2 text-sm text-muted-foreground">
+            <input
+              checked={addAdmin}
+              className="size-4 rounded border-border accent-primary"
+              onChange={(e) => setAddAdmin(e.target.checked)}
+              type="checkbox"
+            />
+            Admin
+          </label>
+          <Button
+            className="h-10 px-4 text-sm"
+            disabled={!addUsername.trim()}
+            onClick={() => addMember.mutate()}
+            type="button"
+          >
+            <UserPlus aria-hidden="true" className="mr-1.5 size-4" />
+            Add
+          </Button>
+        </div>
+      </div>
+
+      {/* Member list card */}
+      <div className="rounded-xl border border-border bg-card overflow-hidden">
+        <div className="border-b border-border px-5 py-3 flex items-center justify-between">
+          <h2 className="text-sm font-semibold text-foreground">
+            Members
+            {members.length > 0 && (
+              <span className="ml-2 font-normal text-muted-foreground">
+                ({members.length})
+              </span>
+            )}
+          </h2>
+          <span className="text-xs text-muted-foreground">
+            {members.filter((m) => m.admin || m.owner).length} admins
+          </span>
+        </div>
+
+        {isLoading ? (
+          <ListSkeleton />
+        ) : members.length > 0 ? (
+          members.map((m) => (
+            <MemberRow
+              key={m.username}
+              member={m}
+              onRemove={(u) => removeMember.mutate(u)}
+              onUpdateRole={(u, a) => updateMember.mutate({ username: u, admin: a })}
+            />
+          ))
+        ) : (
+          <div className="py-16 text-center">
+            <p className="text-sm text-muted-foreground">No members found</p>
+            <p className="mt-1 text-xs text-muted-foreground/60">Add a member above to get started.</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/page/workspace/workplan/chat-conversation.tsx b/src/page/workspace/workplan/chat-conversation.tsx
new file mode 100644
index 0000000..d7917b2
--- /dev/null
+++ b/src/page/workspace/workplan/chat-conversation.tsx
@@ -0,0 +1,677 @@
+import { useState, useEffect, useCallback, useRef, useMemo } from "react";
+import { useParams, useNavigate, useLocation } from "react-router";
+import { ArrowLeft, Sparkles } from "lucide-react";
+import { motion, AnimatePresence } from "motion/react";
+import { client } from "@/client";
+import {
+  PromptInput,
+  PromptInputBody,
+  PromptInputTextarea,
+  PromptInputSubmit,
+  PromptInputFooter,
+  PromptInputTools,
+  PromptInputProvider,
+  usePromptInputController,
+} from "@/components/ai-elements/prompt-input";
+import type {
+  Message,
+  Conversation,
+  Phase,
+  StreamingState,
+  ToolCallState,
+} from "./chat/types";
+import { EMPTY_STREAM } from "./chat/types";
+import { ModelSelectorPopover } from "./chat/model-selector-popover";
+import { MessageBubble } from "./chat/message-bubble";
+import { StreamingView } from "./chat/streaming-view";
+import { CodePreviewProvider } from "./chat/code-preview-context";
+import { CodePreviewPanel } from "./chat/code-preview-panel";
+import { MessageNavDots } from "./chat/message-nav-dots";
+
+// ---- Helpers ----
+
+const formatDateLabel = (date: string) =>
+  new Date(date).toLocaleDateString([], {
+    month: "long",
+    day: "numeric",
+    year: "numeric",
+  });
+
+function parseSSELine(line: string): Record<string, unknown> | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("data: ")) return null;
+  try {
+    return JSON.parse(trimmed.slice(6));
+  } catch {
+    return null;
+  }
+}
+
+function drainSSEBuffer(buffer: string): {
+  chunks: Record<string, unknown>[];
+  remainder: string;
+} {
+  const lines = buffer.split("\n");
+  const remainder = lines.pop() ?? "";
+  const chunks: Record<string, unknown>[] = [];
+  for (const line of lines) {
+    const parsed = parseSSELine(line);
+    if (parsed) chunks.push(parsed);
+  }
+  return { chunks, remainder };
+}
+
+function makeUserMessage(text: string, conversationId: string): Message {
+  return {
+    id: crypto.randomUUID(),
+    conversation_id: conversationId,
+    role: "user",
+    content: text,
+    content_type: "text",
+    created_at: new Date().toISOString(),
+  };
+}
+
+function makeAssistantMessage(
+  id: string,
+  content: string,
+  conversationId: string,
+): Message {
+  return {
+    id,
+    conversation_id: conversationId,
+    role: "assistant",
+    content,
+    content_type: "text",
+    created_at: new Date().toISOString(),
+  };
+}
+
+function safeStringify(v: unknown): string | undefined {
+  if (typeof v === "string") return v;
+  if (v == null) return undefined;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+// ---- Main component ----
+
+export default function WorkplanChatConversation() {
+  const { projectName = "", conversationId = "" } = useParams();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const prefill = (location.state as { prefill?: string } | null)?.prefill;
+
+  const [conversation, setConversation] = useState<Conversation | null>(null);
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [stream, setStream] = useState<StreamingState>(EMPTY_STREAM);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const sendingRef = useRef(false);
+
+  const [sending, setSending] = useState(false);
+  const [modelProvider, setModelProvider] = useState<string>("");
+  const setSendingBoth = useCallback((v: boolean) => {
+    sendingRef.current = v;
+    setSending(v);
+  }, []);
+
+  // ---- Data fetching ----
+
+  const loadData = useCallback(async () => {
+    if (!conversationId) return;
+    try {
+      const [convRes, msgRes] = await Promise.all([
+        client.agentGetConversation(conversationId),
+        client.agentListMessages(conversationId, { limit: 100 }),
+      ]);
+      setConversation(convRes.data);
+      setMessages(msgRes.data as unknown as Message[]);
+      requestAnimationFrame(() => {
+        scrollRef.current?.scrollTo({
+          top: scrollRef.current.scrollHeight,
+          behavior: "instant",
+        });
+      });
+    } catch {
+      // Non-critical; retried on next navigation.
+    }
+  }, [conversationId]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  // ---- Auto-scroll ----
+
+  const scrollToBottom = useCallback(() => {
+    requestAnimationFrame(() => {
+      scrollRef.current?.scrollTo({
+        top: scrollRef.current.scrollHeight,
+        behavior: "smooth",
+      });
+    });
+  }, []);
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [messages, stream, scrollToBottom]);
+
+  // ---- SSE stream processing ----
+
+  function reduceStreamChunk(
+    prev: StreamingState,
+    chunk: Record<string, unknown>,
+  ): {
+    next: StreamingState;
+    addAssistantMessage?: { id: string; content: string };
+    reloadData?: boolean;
+  } {
+    const next: StreamingState = {
+      ...prev,
+      toolCalls: prev.toolCalls.map((tc) => ({ ...tc })),
+    };
+
+    switch (chunk.type) {
+      case "phase_change":
+        next.phase = chunk.phase as Phase;
+        return { next };
+
+      case "thinking":
+        if (typeof chunk.content === "string") {
+          next.phase = "think";
+          next.thinkText += chunk.content;
+        }
+        return { next };
+
+      case "delta":
+        if (typeof chunk.content === "string") {
+          next.phase = "answer";
+          next.answerText += chunk.content;
+        }
+        return { next };
+
+      case "tool_call_started": {
+        next.phase = "act";
+        const tc: ToolCallState = {
+          toolCallId: chunk.tool_call_id as string,
+          toolName: chunk.tool_name as string,
+          arguments: chunk.arguments as string,
+        };
+        if (!next.toolCalls.some((t) => t.toolCallId === tc.toolCallId)) {
+          next.toolCalls = [...next.toolCalls, tc];
+        }
+        return { next };
+      }
+
+      case "tool_call_finished": {
+        next.phase = "act";
+        const idx = next.toolCalls.findIndex(
+          (t) => t.toolCallId === (chunk.tool_call_id as string),
+        );
+        if (idx !== -1) {
+          const updated = { ...next.toolCalls[idx] };
+          updated.output = safeStringify(chunk.output);
+          updated.error = chunk.error as string | null;
+          next.toolCalls = [
+            ...next.toolCalls.slice(0, idx),
+            updated,
+            ...next.toolCalls.slice(idx + 1),
+          ];
+        }
+        return { next };
+      }
+
+      case "done": {
+        const output = safeStringify(chunk.output) ?? next.answerText;
+        const messageId =
+          (chunk.message_id as string) || crypto.randomUUID();
+        return {
+          next: EMPTY_STREAM,
+          addAssistantMessage: { id: messageId, content: output },
+          reloadData: !!chunk.message_id,
+        };
+      }
+
+      case "title_updated":
+        return { next, reloadData: true };
+
+      case "subagent_started":
+        return {
+          next: {
+            ...next,
+            phase: "act" as Phase,
+            toolCalls: [
+              ...next.toolCalls,
+              {
+                toolCallId: chunk.subagent_id as string,
+                toolName: `Subagent: ${chunk.role || "specialist"}`,
+                arguments: chunk.task as string,
+              },
+            ],
+          },
+        };
+
+      case "subagent_completed": {
+        next.phase = "act";
+        const saIdx = next.toolCalls.findIndex(
+          (t) => t.toolCallId === (chunk.subagent_id as string),
+        );
+        if (saIdx !== -1) {
+          const updated = { ...next.toolCalls[saIdx] };
+          updated.output = safeStringify(chunk.output);
+          next.toolCalls = [
+            ...next.toolCalls.slice(0, saIdx),
+            updated,
+            ...next.toolCalls.slice(saIdx + 1),
+          ];
+        }
+        return { next };
+      }
+
+      case "subagent_failed":
+        return { next, reloadData: false };
+
+      case "error":
+        return {
+          next: EMPTY_STREAM,
+          addAssistantMessage: {
+            id: crypto.randomUUID(),
+            content: `Error: ${chunk.error || "Stream error"}`,
+          },
+        };
+
+      default:
+        return { next };
+    }
+  }
+
+  const processChunk = useCallback(
+    (chunk: Record<string, unknown>) => {
+      setStream((prev) => {
+        const { next, addAssistantMessage, reloadData } = reduceStreamChunk(
+          prev,
+          chunk,
+        );
+
+        if (addAssistantMessage && !reloadData) {
+          const msg = makeAssistantMessage(
+            addAssistantMessage.id,
+            addAssistantMessage.content,
+            conversationId,
+          );
+          queueMicrotask(() => {
+            setMessages((prevMessages) => [...prevMessages, msg]);
+          });
+        }
+
+        if (reloadData) {
+          queueMicrotask(() => loadData());
+        }
+
+        return next;
+      });
+    },
+    [conversationId, loadData],
+  );
+
+  // ---- Send message ----
+
+  const sendMessage = useCallback(
+    async (text: string) => {
+      if (!text.trim() || !conversation || sendingRef.current) return;
+
+      setSendingBoth(true);
+      setStream(EMPTY_STREAM);
+
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      setMessages((prev) => [
+        ...prev,
+        makeUserMessage(text, conversationId),
+      ]);
+
+      try {
+        const response = await fetch(
+          `/api/v1/agent/conversations/${conversationId}/stream`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({
+              session_id: conversation.session_id,
+              conversation_id: conversationId,
+              input: text,
+              stream: true,
+            }),
+            signal: controller.signal,
+          },
+        );
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const reader = response.body?.getReader();
+        if (!reader) throw new Error("No response body");
+
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          const { chunks, remainder } = drainSSEBuffer(buffer);
+          buffer = remainder;
+
+          for (const chunk of chunks) {
+            processChunk(chunk);
+          }
+        }
+
+        if (buffer.trim()) {
+          const { chunks } = drainSSEBuffer(buffer + "\n");
+          for (const chunk of chunks) {
+            processChunk(chunk);
+          }
+        }
+      } catch (err: unknown) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        setMessages((prev) => [
+          ...prev,
+          makeAssistantMessage(
+            crypto.randomUUID(),
+            err instanceof Error
+              ? `Error: ${err.message}`
+              : "Request failed",
+            conversationId,
+          ),
+        ]);
+      } finally {
+        setSendingBoth(false);
+        abortRef.current = null;
+      }
+    },
+    [conversation, conversationId, processChunk, setSendingBoth],
+  );
+
+  // ---- Prefill (quick-start) ----
+
+  const prefilledRef = useRef(false);
+  useEffect(() => {
+    if (prefill && !prefilledRef.current && conversation && !sending) {
+      prefilledRef.current = true;
+      const timer = setTimeout(() => {
+        sendMessage(prefill);
+      }, 100);
+      return () => clearTimeout(timer);
+    }
+  }, [prefill, conversation, sending, sendMessage]);
+
+  // ---- Stop generation ----
+
+  const handleStop = useCallback(() => {
+    abortRef.current?.abort();
+  }, []);
+
+  // ---- Computed values ----
+
+  const messageGroups = useMemo(() => {
+    const groups: { date: string; messages: Message[] }[] = [];
+    for (const msg of messages) {
+      const ds = formatDateLabel(msg.created_at);
+      const last = groups[groups.length - 1];
+      if (last?.date === ds) {
+        last.messages.push(msg);
+      } else {
+        groups.push({ date: ds, messages: [msg] });
+      }
+    }
+    return groups;
+  }, [messages]);
+
+  const hasActiveStream = sending || stream.phase !== "idle";
+
+  return (
+    <PromptInputProvider>
+      <CodePreviewProvider>
+        <div className="flex h-full">
+          <div className="flex min-w-0 flex-1 flex-col">
+            <ChatInner
+              projectName={projectName}
+              navigate={navigate}
+              conversation={conversation}
+              messageGroups={messageGroups}
+              stream={stream}
+              hasActiveStream={hasActiveStream}
+              sending={sending}
+              modelProvider={modelProvider}
+              onModelChange={(_name, provider) => {
+                setModelProvider(provider);
+              }}
+              scrollRef={scrollRef}
+              sendMessage={sendMessage}
+              handleStop={handleStop}
+            />
+          </div>
+          <CodePreviewPanel />
+        </div>
+      </CodePreviewProvider>
+    </PromptInputProvider>
+  );
+}
+
+// ---- Inner component ----
+
+function ChatInner({
+  projectName,
+  navigate,
+  conversation,
+  messageGroups,
+  stream,
+  hasActiveStream,
+  sending,
+  modelProvider,
+  onModelChange,
+  scrollRef,
+  sendMessage,
+  handleStop,
+}: {
+  projectName: string;
+  navigate: ReturnType<typeof useNavigate>;
+  conversation: Conversation | null;
+  messageGroups: { date: string; messages: Message[] }[];
+  stream: StreamingState;
+  hasActiveStream: boolean;
+  sending: boolean;
+  modelProvider: string;
+  onModelChange: (name: string, provider: string) => void;
+  scrollRef: React.RefObject<HTMLDivElement | null>;
+  sendMessage: (text: string) => Promise<void>;
+  handleStop: () => void;
+}) {
+  const { textInput } = usePromptInputController();
+  const allMessages = useMemo(
+    () => messageGroups.flatMap((g) => g.messages),
+    [messageGroups],
+  );
+
+  const handleSubmit = useCallback(
+    (text: string) => {
+      if (text.trim()) {
+        sendMessage(text);
+        textInput.clear();
+      }
+    },
+    [sendMessage, textInput],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      if (e.key === "Enter" && !e.shiftKey && !sending) {
+        e.preventDefault();
+        const text = textInput.value;
+        if (text.trim()) {
+          sendMessage(text);
+          textInput.clear();
+        }
+      }
+    },
+    [sendMessage, textInput, sending],
+  );
+
+  return (
+    <div className="flex h-full flex-col overflow-hidden bg-background">
+      {/* Header */}
+      <header className="flex h-12 shrink-0 items-center gap-2.5 border-b border-border/60 bg-card/50 px-4 backdrop-blur-sm">
+        <motion.button
+          type="button"
+          whileHover={{ scale: 1.05, x: -1 }}
+          whileTap={{ scale: 0.92 }}
+          className="inline-flex size-8 cursor-pointer items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          onClick={() => navigate(`/${projectName}/workplan/chat`)}
+          aria-label="Back to chat list"
+        >
+          <ArrowLeft className="size-4" aria-hidden="true" />
+        </motion.button>
+
+        <div className="flex min-w-0 flex-1 items-center gap-2">
+          <div className="grid size-6 place-items-center rounded-md bg-primary/10">
+            <Sparkles className="size-3 text-primary/70" />
+          </div>
+          <h1 className="truncate text-sm font-semibold text-foreground">
+            {conversation?.title ?? "Loading..."}
+          </h1>
+        </div>
+      </header>
+
+      {/* Messages */}
+      <div
+        className="scrollbar-none relative min-h-0 flex-1 overflow-y-auto overscroll-contain px-4 py-6"
+        ref={scrollRef}
+        role="log"
+        aria-label="Conversation messages"
+        aria-live="polite"
+      >
+        <MessageNavDots
+          messages={allMessages}
+          scrollContainerRef={scrollRef}
+        />
+
+        <AnimatePresence>
+          {messageGroups.length === 0 && !hasActiveStream && (
+            <motion.div
+              initial={{ opacity: 0, scale: 0.96 }}
+              animate={{ opacity: 1, scale: 1 }}
+              exit={{ opacity: 0, scale: 0.96 }}
+              transition={{ duration: 0.3, ease: "easeOut" }}
+              className="flex h-full items-center justify-center"
+            >
+              <EmptyConversationState />
+            </motion.div>
+          )}
+        </AnimatePresence>
+
+        <div className="mx-auto max-w-3xl space-y-6">
+          {messageGroups.map((group) => (
+            <div key={group.date}>
+              {/* Elegant date separator */}
+              <div className="my-8 flex items-center justify-center gap-3">
+                <div className="h-px w-12 bg-gradient-to-r from-transparent to-border/50" />
+                <span className="rounded-full bg-muted/50 px-3 py-1 text-[11px] font-medium text-muted-foreground/60 shadow-sm">
+                  {group.date}
+                </span>
+                <div className="h-px w-12 bg-gradient-to-l from-transparent to-border/50" />
+              </div>
+
+              <div className="space-y-4">
+                {group.messages.map((msg) => (
+                  <motion.div
+                    key={msg.id}
+                    data-msg-index={allMessages.indexOf(msg)}
+                    data-msg-role={msg.role}
+                    initial={{ opacity: 0, y: 10 }}
+                    animate={{ opacity: 1, y: 0 }}
+                    transition={{ duration: 0.25, ease: "easeOut" }}
+                  >
+                    <MessageBubble msg={msg} modelProvider={modelProvider} />
+                  </motion.div>
+                ))}
+              </div>
+            </div>
+          ))}
+
+          <AnimatePresence>
+            {hasActiveStream && (
+              <motion.div
+                key="streaming"
+                initial={{ opacity: 0, y: 10 }}
+                animate={{ opacity: 1, y: 0 }}
+                exit={{ opacity: 0, y: 6 }}
+                transition={{ duration: 0.2 }}
+              >
+                <StreamingView stream={stream} modelProvider={modelProvider} />
+              </motion.div>
+            )}
+          </AnimatePresence>
+        </div>
+      </div>
+
+      {/* Composer */}
+      <footer className="shrink-0 border-t border-border/60 bg-card/70 backdrop-blur-md">
+        <div className="mx-auto max-w-3xl px-4 py-3">
+          <PromptInput
+            globalDrop={false}
+            onSubmit={({ text }) => handleSubmit(text)}
+          >
+            <PromptInputBody>
+              <PromptInputTextarea
+                className="min-h-[48px] max-h-[200px] resize-none rounded-xl border-border/60 bg-muted/40 text-sm shadow-inner transition-colors focus-visible:bg-background focus-visible:ring-1 focus-visible:ring-primary/20"
+                placeholder="Type a message…"
+                onKeyDown={handleKeyDown}
+              />
+            </PromptInputBody>
+            <PromptInputFooter>
+              <PromptInputTools>
+                <ModelSelectorPopover
+                  sessionId={conversation?.session_id}
+                  onModelChange={onModelChange}
+                />
+              </PromptInputTools>
+              <PromptInputSubmit
+                status={sending ? "streaming" : undefined}
+                onStop={handleStop}
+              />
+            </PromptInputFooter>
+          </PromptInput>
+          <p className="mt-1.5 text-center text-[11px] text-muted-foreground/30">
+            AI responses may be inaccurate. Verify important information.
+          </p>
+        </div>
+      </footer>
+    </div>
+  );
+}
+
+/** Empty state shown when conversation has no messages. */
+function EmptyConversationState() {
+  return (
+    <div className="text-center">
+      <div className="mx-auto grid size-16 place-items-center rounded-2xl bg-gradient-to-br from-primary/10 to-primary/[0.02] ring-1 ring-primary/10 shadow-sm">
+        <Sparkles className="size-7 text-primary/30" />
+      </div>
+      <p className="mt-4 text-sm font-medium text-muted-foreground/60">
+        Start a conversation
+      </p>
+      <p className="mt-1 text-xs text-muted-foreground/35">
+        Type a message below to begin
+      </p>
+    </div>
+  );
+}
diff --git a/src/page/workspace/workplan/chat-list.tsx b/src/page/workspace/workplan/chat-list.tsx
new file mode 100644
index 0000000..5c3a10d
--- /dev/null
+++ b/src/page/workspace/workplan/chat-list.tsx
@@ -0,0 +1,164 @@
+import { useCallback } from "react";
+import { useParams, useNavigate } from "react-router";
+import { Plus, MessageSquare, Code2, Bug, Lightbulb, Wand2 } from "lucide-react";
+import { motion } from "motion/react";
+import { client } from "@/client";
+import { Button } from "@/components/ui/button";
+import { useWorkspaceSessions } from "./chat/use-sessions";
+import { ensureWorkspaceSession } from "./chat/use-session";
+
+interface SuggestionCard {
+  title: string;
+  body: string;
+  icon: React.ComponentType<{ className?: string }>;
+  gradient: string;
+}
+
+const SUGGESTIONS: SuggestionCard[] = [
+  {
+    title: "Code Review",
+    body: "Review my pull request for bugs and improvements",
+    icon: Code2,
+    gradient: "from-emerald-500/10 to-emerald-500/[0.02]",
+  },
+  {
+    title: "Debug Help",
+    body: "Help me diagnose this failing test case",
+    icon: Bug,
+    gradient: "from-amber-500/10 to-amber-500/[0.02]",
+  },
+  {
+    title: "Explain Code",
+    body: "Explain how this algorithm works step by step",
+    icon: Lightbulb,
+    gradient: "from-violet-500/10 to-violet-500/[0.02]",
+  },
+  {
+    title: "Refactor",
+    body: "Suggest refactoring for better readability",
+    icon: Wand2,
+    gradient: "from-sky-500/10 to-sky-500/[0.02]",
+  },
+];
+
+/**
+ * Landing / empty-state page shown when no conversation is selected.
+ */
+export default function WorkplanChatList() {
+  const { projectName = "" } = useParams();
+  const navigate = useNavigate();
+  const { sessionsRef } = useWorkspaceSessions(projectName);
+
+  const startConversation = useCallback(
+    async (title: string, prefillBody?: string) => {
+      try {
+        const sessionId = await ensureWorkspaceSession(
+          projectName,
+          sessionsRef.current,
+        );
+        if (!sessionId) return;
+
+        const r = await client.agentCreateConversation(sessionId, { title });
+        navigate(`/${projectName}/workplan/chat/${r.data.id}`, {
+          state: prefillBody ? { prefill: prefillBody } : undefined,
+        });
+      } catch {
+        // Silently fail — user can retry via UI.
+      }
+    },
+    [projectName, navigate, sessionsRef],
+  );
+
+  const handleNewChat = useCallback(() => {
+    startConversation("New Chat");
+  }, [startConversation]);
+
+  const handleQuickStart = useCallback(
+    (title: string, body: string) => {
+      startConversation(title, body);
+    },
+    [startConversation],
+  );
+
+  return (
+    <div className="flex h-full items-center justify-center px-8">
+      <motion.div
+        initial={{ opacity: 0, y: 20 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.4, ease: "easeOut" }}
+        className="max-w-md text-center"
+      >
+        {/* Hero icon */}
+        <div className="mx-auto grid size-20 place-items-center rounded-2xl bg-gradient-to-br from-primary/15 to-primary/[0.03] ring-1 ring-primary/10 shadow-sm">
+          <MessageSquare
+            className="size-9 text-primary/30"
+            aria-hidden="true"
+          />
+        </div>
+
+        <h1 className="mt-6 text-xl font-bold tracking-tight text-foreground">
+          AI Assistant
+        </h1>
+        <p className="mt-2 text-sm leading-relaxed text-muted-foreground/70">
+          Start a new conversation with the AI assistant. Ask questions, get
+          code help, discuss ideas, and more.
+        </p>
+
+        <div className="mt-6 flex items-center justify-center gap-3">
+          <motion.div whileHover={{ scale: 1.03 }} whileTap={{ scale: 0.97 }}>
+            <Button
+              className="cursor-pointer shadow-sm"
+              onClick={handleNewChat}
+              size="default"
+              variant="default"
+            >
+              <Plus className="mr-2 size-4" aria-hidden="true" />
+              New Chat
+            </Button>
+          </motion.div>
+        </div>
+
+        {/* Suggestion cards */}
+        <div className="mt-10 grid grid-cols-2 gap-2.5 text-left">
+          {SUGGESTIONS.map((suggestion, i) => {
+            const Icon = suggestion.icon;
+            return (
+              <motion.button
+                key={suggestion.title}
+                initial={{ opacity: 0, y: 12 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ duration: 0.3, delay: 0.1 + i * 0.06 }}
+                whileHover={{
+                  scale: 1.02,
+                  transition: { duration: 0.15 },
+                }}
+                whileTap={{ scale: 0.98 }}
+                type="button"
+                className={`
+                  group cursor-pointer rounded-xl border border-border/40 bg-gradient-to-br ${suggestion.gradient}
+                  px-4 py-3.5 text-left transition-all duration-200
+                  hover:border-border/80 hover:shadow-sm hover:ring-1 hover:ring-primary/10
+                  focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring
+                `}
+                onClick={() =>
+                  handleQuickStart(suggestion.title, suggestion.body)
+                }
+                aria-label={`${suggestion.title}: ${suggestion.body}`}
+              >
+                <div className="flex items-center gap-2">
+                  <Icon className="size-3.5 text-muted-foreground/50 transition-colors group-hover:text-foreground/70" />
+                  <p className="text-[13px] font-medium text-foreground">
+                    {suggestion.title}
+                  </p>
+                </div>
+                <p className="mt-1.5 text-[11px] leading-relaxed text-muted-foreground/50">
+                  {suggestion.body}
+                </p>
+              </motion.button>
+            );
+          })}
+        </div>
+      </motion.div>
+    </div>
+  );
+}
diff --git a/src/page/workspace/workplan/chat-sidebar.tsx b/src/page/workspace/workplan/chat-sidebar.tsx
new file mode 100644
index 0000000..9c2f035
--- /dev/null
+++ b/src/page/workspace/workplan/chat-sidebar.tsx
@@ -0,0 +1,237 @@
+import { useState, useEffect, useCallback, useMemo } from "react";
+import { useParams, useNavigate } from "react-router";
+import { Plus, MessageSquare, Bot } from "lucide-react";
+import { motion, AnimatePresence } from "motion/react";
+import { client } from "@/client";
+import type { ConversationWithSessionResponse } from "@/client/models/conversationWithSessionResponse";
+import { Shimmer } from "@/components/ai-elements/shimmer";
+import { ChatItem } from "./chat/chat-item";
+import { useWorkspaceSessions } from "./chat/use-sessions";
+import { ensureWorkspaceSession } from "./chat/use-session";
+
+
+const SKELETON_COUNT = 3;
+
+interface GroupedConversations {
+  today: ConversationWithSessionResponse[];
+  yesterday: ConversationWithSessionResponse[];
+  recent: ConversationWithSessionResponse[];
+  older: ConversationWithSessionResponse[];
+}
+
+function groupConversations(
+  convs: ConversationWithSessionResponse[],
+): GroupedConversations {
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const yesterday = new Date(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+  const sevenDaysAgo = new Date(today);
+  sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
+
+  const groups: GroupedConversations = {
+    today: [],
+    yesterday: [],
+    recent: [],
+    older: [],
+  };
+
+  for (const conv of convs) {
+    const date = new Date(conv.last_message_at || conv.created_at);
+    const d = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+
+    if (d.getTime() === today.getTime()) {
+      groups.today.push(conv);
+    } else if (d.getTime() === yesterday.getTime()) {
+      groups.yesterday.push(conv);
+    } else if (d.getTime() >= sevenDaysAgo.getTime()) {
+      groups.recent.push(conv);
+    } else {
+      groups.older.push(conv);
+    }
+  }
+
+  return groups;
+}
+
+export function WorkplanChatSidebar() {
+  const { projectName = "", conversationId } = useParams();
+  const navigate = useNavigate();
+  const [conversations, setConversations] = useState<
+    ConversationWithSessionResponse[]
+  >([]);
+  const [loadingConvs, setLoadingConvs] = useState(true);
+  const { sessionsRef } = useWorkspaceSessions(projectName);
+
+  const loadConversations = useCallback(async () => {
+    try {
+      setLoadingConvs(true);
+      const convsRes = await client
+        .agentListAllConversations({ wk: projectName })
+        .catch(() => ({
+          data: [] as ConversationWithSessionResponse[],
+        }));
+
+      const sorted = [...convsRes.data].sort((a, b) => {
+        const da = a.last_message_at
+          ? new Date(a.last_message_at).getTime()
+          : new Date(a.created_at).getTime();
+        const db = b.last_message_at
+          ? new Date(b.last_message_at).getTime()
+          : new Date(b.created_at).getTime();
+        return db - da;
+      });
+      setConversations(sorted);
+    } finally {
+      setLoadingConvs(false);
+    }
+  }, [projectName]);
+
+  useEffect(() => {
+    loadConversations();
+  }, [loadConversations]);
+
+  const handleNewChat = useCallback(async () => {
+    const sessionId = await ensureWorkspaceSession(
+      projectName,
+      sessionsRef.current,
+    );
+    if (!sessionId) return;
+
+    try {
+      const res = await client.agentCreateConversation(sessionId, {
+        title: "New Chat",
+      });
+      const conv =
+        res.data as unknown as ConversationWithSessionResponse;
+      setConversations((prev) => [conv, ...prev]);
+      navigate(`/${projectName}/workplan/chat/${conv.id}`);
+    } catch {
+      // User may retry via UI.
+    }
+  }, [projectName, sessionsRef, navigate]);
+
+  const handleDelete = useCallback(
+    async (id: string) => {
+      try {
+        await client.agentDeleteConversation(id);
+        if (conversationId === id) {
+          navigate(`/${projectName}/workplan/chat`);
+        }
+        setConversations((prev) => prev.filter((c) => c.id !== id));
+      } catch {
+        // Deletion failed; item remains in list.
+      }
+    },
+    [conversationId, navigate, projectName],
+  );
+
+  const grouped = useMemo(
+    () => groupConversations(conversations),
+    [conversations],
+  );
+
+  const isLoading = loadingConvs;
+
+  const groupOrder: Array<{
+    key: keyof GroupedConversations;
+    label: string;
+  }> = [
+    { key: "today", label: "Today" },
+    { key: "yesterday", label: "Yesterday" },
+    { key: "recent", label: "Previous 7 Days" },
+    { key: "older", label: "Older" },
+  ];
+
+  return (
+    <div className="flex flex-col h-full" role="navigation" aria-label="AI Chats">
+      {/* Header */}
+      <div className="mb-2 flex items-center justify-between px-3 py-2">
+        <div className="flex items-center gap-2">
+          <div className="grid size-6 place-items-center rounded-md bg-primary/10">
+            <MessageSquare className="size-3.5 text-primary/70" />
+          </div>
+          <span className="text-xs font-semibold uppercase tracking-[0.06em] text-muted-foreground">
+            AI Chats
+          </span>
+        </div>
+        <motion.button
+          type="button"
+          whileHover={{ scale: 1.05 }}
+          whileTap={{ scale: 0.92 }}
+          className="inline-flex size-6 cursor-pointer items-center justify-center rounded-md bg-muted/60 text-muted-foreground/60 transition-colors hover:bg-primary/10 hover:text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          onClick={handleNewChat}
+          aria-label="New chat"
+        >
+          <Plus className="size-3" aria-hidden="true" />
+        </motion.button>
+      </div>
+
+      {/* Conversation list */}
+      <div className="flex-1 overflow-y-auto overscroll-contain px-1.5">
+        {isLoading && (
+          <div className="space-y-1 px-1">
+            {Array.from({ length: SKELETON_COUNT }).map((_, i) => (
+              <div className="h-9 rounded-lg px-2.5 py-2" key={i}>
+                <Shimmer duration={1.8} spread={1.5}>
+                  {"\u00A0".repeat(24 + i * 6)}
+                </Shimmer>
+              </div>
+            ))}
+          </div>
+        )}
+
+        <AnimatePresence>
+          {!isLoading && conversations.length === 0 && (
+            <motion.div
+              initial={{ opacity: 0, y: 8 }}
+              animate={{ opacity: 1, y: 0 }}
+              className="flex flex-col items-center justify-center gap-3 py-10 px-4 text-center"
+            >
+              <div className="grid size-12 place-items-center rounded-2xl bg-muted/30">
+                <Bot className="size-5 text-muted-foreground/25" />
+              </div>
+              <div>
+                <p className="text-xs font-medium text-muted-foreground/70">
+                  No chats yet
+                </p>
+                <p className="mt-0.5 text-[11px] text-muted-foreground/40">
+                  Click + to start a conversation
+                </p>
+              </div>
+            </motion.div>
+          )}
+        </AnimatePresence>
+
+        {!isLoading &&
+          groupOrder.map(
+            ({ key, label }) =>
+              grouped[key].length > 0 && (
+                <div key={key} className="mb-2">
+                  <div className="mb-1 flex items-center gap-2 px-2.5 py-1">
+                    <span className="h-px flex-1 bg-border/30" />
+                    <span className="text-[10px] font-medium uppercase tracking-wider text-muted-foreground/40">
+                      {label}
+                    </span>
+                    <span className="h-px flex-1 bg-border/30" />
+                  </div>
+                  <div className="space-y-0.5">
+                    {grouped[key].map((conv) => (
+                      <ChatItem
+                        key={conv.id}
+                        conv={conv}
+                        active={conversationId === conv.id}
+                        onSelect={() =>
+                          navigate(`/${projectName}/workplan/chat/${conv.id}`)
+                        }
+                        onDelete={handleDelete}
+                      />
+                    ))}
+                  </div>
+                </div>
+              ),
+          )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/page/workspace/workplan/chat/chat-item.tsx b/src/page/workspace/workplan/chat/chat-item.tsx
new file mode 100644
index 0000000..61dd248
--- /dev/null
+++ b/src/page/workspace/workplan/chat/chat-item.tsx
@@ -0,0 +1,86 @@
+import { memo } from "react";
+import { Trash2 } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { formatTime, truncateTitle } from "./utils";
+import type { ConversationWithSessionResponse } from "@/client/models/conversationWithSessionResponse";
+
+interface ChatItemProps {
+  conv: ConversationWithSessionResponse;
+  active: boolean;
+  onSelect: () => void;
+  onDelete: (id: string) => void;
+}
+
+export const ChatItem = memo(function ChatItem({
+  conv,
+  active,
+  onSelect,
+  onDelete,
+}: ChatItemProps) {
+  const initials = (conv.title || "AI").slice(0, 2).toUpperCase();
+
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      aria-current={active ? "page" : undefined}
+      aria-label={conv.title || "Untitled chat"}
+      className={cn(
+        "group relative flex w-full cursor-pointer items-center gap-2.5 rounded-lg px-2.5 py-2 text-left transition-all duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        active
+          ? "bg-primary/[0.08] text-foreground shadow-[inset_0_0_0_1px_var(--color-primary)/15]"
+          : "text-muted-foreground hover:bg-accent/50 hover:text-foreground hover:shadow-sm",
+      )}
+      onClick={onSelect}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onSelect();
+        }
+      }}
+    >
+      {/* Active indicator pill */}
+      {active && (
+        <span className="absolute left-0 top-1/2 h-5 w-[3px] -translate-y-1/2 rounded-r-full bg-primary/70" />
+      )}
+
+      {/* Avatar */}
+      <span
+        className={cn(
+          "grid size-7 shrink-0 place-items-center rounded-lg text-[10px] font-bold transition-colors",
+          active
+            ? "bg-primary/15 text-primary/70"
+            : "bg-muted/60 text-muted-foreground/50 group-hover:bg-primary/10 group-hover:text-primary/60",
+        )}
+        aria-hidden="true"
+      >
+        {initials}
+      </span>
+
+      {/* Title & time */}
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center justify-between gap-1.5">
+          <span className="truncate text-[12px] font-medium leading-tight">
+            {truncateTitle(conv.title)}
+          </span>
+          <span className="shrink-0 text-[10px] tabular-nums text-muted-foreground/40">
+            {formatTime(conv.last_message_at || conv.created_at)}
+          </span>
+        </div>
+      </div>
+
+      {/* Delete */}
+      <button
+        type="button"
+        className="shrink-0 cursor-pointer rounded-md p-1 text-muted-foreground/30 opacity-0 transition-all duration-200 hover:bg-destructive/10 hover:text-destructive focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring group-hover:opacity-100"
+        onClick={(e) => {
+          e.stopPropagation();
+          onDelete(conv.id);
+        }}
+        aria-label={`Delete chat "${conv.title || "Untitled"}"`}
+      >
+        <Trash2 className="size-3" aria-hidden="true" />
+      </button>
+    </div>
+  );
+});
diff --git a/src/page/workspace/workplan/chat/code-preview-context.tsx b/src/page/workspace/workplan/chat/code-preview-context.tsx
new file mode 100644
index 0000000..8523dc8
--- /dev/null
+++ b/src/page/workspace/workplan/chat/code-preview-context.tsx
@@ -0,0 +1,54 @@
+import { createContext, useCallback, useContext, useState } from "react";
+
+export interface CodePreviewPayload {
+  id: string;
+  code: string;
+  language: string;
+  lineCount: number;
+  title?: string;
+  subtitle?: string;
+}
+
+interface CodePreviewContextValue {
+  activeCode: CodePreviewPayload | null;
+  openCodePreview: (payload: CodePreviewPayload) => void;
+  closeCodePreview: () => void;
+}
+
+const CodePreviewContext = createContext<CodePreviewContextValue | null>(null);
+
+export function CodePreviewProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [activeCode, setActiveCode] = useState<CodePreviewPayload | null>(
+    null,
+  );
+
+  const openCodePreview = useCallback((payload: CodePreviewPayload) => {
+    setActiveCode(payload);
+  }, []);
+
+  const closeCodePreview = useCallback(() => {
+    setActiveCode(null);
+  }, []);
+
+  return (
+    <CodePreviewContext.Provider
+      value={{ activeCode, openCodePreview, closeCodePreview }}
+    >
+      {children}
+    </CodePreviewContext.Provider>
+  );
+}
+
+export function useCodePreview() {
+  const ctx = useContext(CodePreviewContext);
+  if (!ctx) {
+    throw new Error(
+      "useCodePreview must be used within CodePreviewProvider",
+    );
+  }
+  return ctx;
+}
diff --git a/src/page/workspace/workplan/chat/code-preview-panel.tsx b/src/page/workspace/workplan/chat/code-preview-panel.tsx
new file mode 100644
index 0000000..b71e7a3
--- /dev/null
+++ b/src/page/workspace/workplan/chat/code-preview-panel.tsx
@@ -0,0 +1,217 @@
+import { memo, useCallback, useMemo, useState, useEffect } from "react";
+import { motion, AnimatePresence } from "motion/react";
+import { Check, Copy, PanelRightClose, Code2, Eye } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { MarkdownRenderer } from "@/components/MarkdownRenderer";
+import { useCodePreview } from "./code-preview-context";
+
+const PREVIEW_LANGUAGES = new Set(["html", "markdown", "md", "latex", "tex"]);
+
+function canPreview(language: string): boolean {
+  return PREVIEW_LANGUAGES.has(language.toLowerCase());
+}
+
+type ViewMode = "code" | "preview";
+
+export const CodePreviewPanel = memo(function CodePreviewPanel() {
+  const { activeCode, closeCodePreview } = useCodePreview();
+  const [copied, setCopied] = useState(false);
+  const [viewMode, setViewMode] = useState<ViewMode>("code");
+
+  const language = activeCode?.language?.toLowerCase() ?? "";
+  const showPreviewToggle = canPreview(language);
+
+  useEffect(() => {
+    if (activeCode) setViewMode("code");
+  }, [activeCode?.id]);
+
+  const lines = useMemo(
+    () => (activeCode?.code ?? "").replace(/\n$/, "").split("\n"),
+    [activeCode?.code],
+  );
+
+  const handleCopy = useCallback(() => {
+    if (!activeCode?.code) return;
+    navigator.clipboard.writeText(activeCode.code).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1600);
+    });
+  }, [activeCode?.code]);
+
+  const isOpen = activeCode !== null;
+  const isHTML = language === "html";
+  const isLatex = language === "latex" || language === "tex";
+  const isMarkdown = language === "markdown" || language === "md";
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <motion.aside
+          initial={{ width: 0, opacity: 0 }}
+          animate={{
+            width: "min(48vw, 760px)",
+            opacity: 1,
+          }}
+          exit={{ width: 0, opacity: 0 }}
+          transition={{ duration: 0.3, ease: [0.25, 0.46, 0.45, 0.94] }}
+          className="flex h-full shrink-0 flex-col overflow-hidden border-l border-border/60 bg-card/95 shadow-[-4px_0_24px_-8px_rgba(0,0,0,0.06)] backdrop-blur-sm"
+        >
+          <div className="flex h-full w-full flex-col">
+            {/* Header */}
+            <div className="flex h-11 shrink-0 items-center justify-between gap-3 border-b border-border/40 bg-muted/20 px-4">
+              <div className="flex min-w-0 items-center gap-2.5">
+                <div className="grid size-7 place-items-center rounded-lg bg-primary/10">
+                  <Code2 className="size-3.5 text-primary/70" />
+                </div>
+                <div className="min-w-0">
+                  <div className="truncate text-sm font-medium text-foreground">
+                    {activeCode?.title || activeCode?.language || "Code"}
+                  </div>
+                  <div className="text-[11px] text-muted-foreground/60">
+                    {activeCode?.subtitle ??
+                      `${activeCode?.lineCount ?? lines.length} line${(activeCode?.lineCount ?? lines.length) !== 1 ? "s" : ""}`}
+                  </div>
+                </div>
+              </div>
+
+              <div className="flex items-center gap-1">
+                {/* Code / Preview toggle */}
+                {showPreviewToggle && (
+                  <div className="mr-1.5 flex items-center overflow-hidden rounded-lg border border-border/60 bg-muted/30 p-0.5">
+                    <button
+                      className={`flex items-center gap-1 rounded-md px-2 py-1 text-[11px] font-medium transition-all ${
+                        viewMode === "code"
+                          ? "bg-card text-foreground shadow-sm"
+                          : "text-muted-foreground/60 hover:text-foreground"
+                      }`}
+                      onClick={() => setViewMode("code")}
+                      type="button"
+                    >
+                      <Code2 className="size-3" />
+                      Code
+                    </button>
+                    <button
+                      className={`flex items-center gap-1 rounded-md px-2 py-1 text-[11px] font-medium transition-all ${
+                        viewMode === "preview"
+                          ? "bg-card text-foreground shadow-sm"
+                          : "text-muted-foreground/60 hover:text-foreground"
+                      }`}
+                      onClick={() => setViewMode("preview")}
+                      type="button"
+                    >
+                      <Eye className="size-3" />
+                      Preview
+                    </button>
+                  </div>
+                )}
+
+                <Button
+                  className="size-8"
+                  disabled={!activeCode}
+                  onClick={handleCopy}
+                  size="icon"
+                  variant="ghost"
+                  aria-label={copied ? "Copied" : "Copy code"}
+                >
+                  {copied ? (
+                    <Check className="size-4 text-emerald-500" />
+                  ) : (
+                    <Copy className="size-4" />
+                  )}
+                </Button>
+                <Button
+                  className="size-8"
+                  onClick={closeCodePreview}
+                  size="icon"
+                  variant="ghost"
+                  aria-label="Close code preview"
+                >
+                  <PanelRightClose className="size-4" />
+                </Button>
+              </div>
+            </div>
+
+            {/* Content */}
+            <div className="min-h-0 flex-1 overflow-auto">
+              {viewMode === "preview" ? (
+                <PreviewContent
+                  code={activeCode?.code ?? ""}
+                  isHTML={isHTML}
+                  isLatex={isLatex}
+                  isMarkdown={isMarkdown}
+                />
+              ) : (
+                <div className="grid min-w-max grid-cols-[auto_1fr]">
+                  {/* Line numbers */}
+                  <div
+                    aria-hidden="true"
+                    className="select-none border-r border-border/30 bg-muted/15 px-3 py-4 text-right font-mono text-[11px] tabular-nums leading-[1.7] text-muted-foreground/30"
+                  >
+                    {lines.map((_, i) => (
+                      <div key={i}>{i + 1}</div>
+                    ))}
+                  </div>
+                  {/* Code */}
+                  <pre className="m-0 overflow-x-auto px-4 py-4 font-mono text-[13px] leading-[1.7] text-foreground/85">
+                    <code>{activeCode?.code ?? ""}</code>
+                  </pre>
+                </div>
+              )}
+            </div>
+          </div>
+        </motion.aside>
+      )}
+    </AnimatePresence>
+  );
+});
+
+/** Renders code content as a preview. */
+const PreviewContent = memo(function PreviewContent({
+  code,
+  isHTML,
+  isLatex,
+  isMarkdown,
+}: {
+  code: string;
+  isHTML: boolean;
+  isLatex: boolean;
+  isMarkdown: boolean;
+}) {
+  if (isHTML) {
+    return (
+      <iframe
+        className="h-full w-full border-0"
+        sandbox="allow-scripts allow-same-origin"
+        srcDoc={code}
+        title="HTML Preview"
+      />
+    );
+  }
+
+  if (isMarkdown) {
+    return (
+      <div className="px-6 py-5">
+        <MarkdownRenderer content={code} />
+      </div>
+    );
+  }
+
+  if (isLatex) {
+    return (
+      <div className="px-6 py-5">
+        <pre className="whitespace-pre-wrap font-mono text-sm text-foreground/80">
+          {code}
+        </pre>
+        <p className="mt-4 text-xs text-muted-foreground/50">
+          LaTeX rendering requires a math engine (KaTeX / MathJax).
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <pre className="whitespace-pre-wrap p-5 font-mono text-sm text-foreground/80">
+      {code}
+    </pre>
+  );
+});
diff --git a/src/page/workspace/workplan/chat/message-bubble.tsx b/src/page/workspace/workplan/chat/message-bubble.tsx
new file mode 100644
index 0000000..27197a4
--- /dev/null
+++ b/src/page/workspace/workplan/chat/message-bubble.tsx
@@ -0,0 +1,112 @@
+import { memo } from "react";
+import { User, Sparkles } from "lucide-react";
+import { cn } from "@/lib/utils";
+import {
+  Reasoning,
+  ReasoningTrigger,
+  ReasoningContent,
+} from "@/components/ai-elements/reasoning";
+import { MarkdownRenderer } from "@/components/MarkdownRenderer";
+import { getProviderIcon } from "./provider-icon";
+import { isVisibleToolCall } from "./tool-utils";
+import { ToolCallList } from "./tool-call-list";
+import { useCodePreview } from "./code-preview-context";
+import type { Message } from "./types";
+
+interface MessageBubbleProps {
+  msg: Message;
+  modelProvider?: string;
+}
+
+export const MessageBubble = memo(function MessageBubble({
+  msg,
+  modelProvider,
+}: MessageBubbleProps) {
+  const isUser = msg.role === "user";
+  const { openCodePreview } = useCodePreview();
+  const hasToolCalls =
+    !isUser &&
+    msg.tool_calls &&
+    msg.tool_calls.some((tc) => isVisibleToolCall(tc.name));
+
+  return (
+    <div
+      className={cn("flex gap-3", isUser ? "justify-end" : "justify-start")}
+      role="article"
+      aria-label={isUser ? "Your message" : "Assistant message"}
+    >
+      {!isUser && <AIAvatar providerName={modelProvider} />}
+
+      <div className="min-w-0 max-w-[85%] space-y-2">
+        {/* Reasoning content */}
+        {msg.reasoning_content && (
+          <Reasoning defaultOpen={false}>
+            <ReasoningTrigger />
+            <ReasoningContent>{msg.reasoning_content}</ReasoningContent>
+          </Reasoning>
+        )}
+
+        {/* Tool calls */}
+        {hasToolCalls && <ToolCallList toolCalls={msg.tool_calls!} />}
+
+        {/* Message content */}
+        <div
+          className={cn(
+            "relative overflow-hidden text-sm leading-relaxed shadow-sm",
+            isUser
+              ? "rounded-2xl rounded-tr-sm bg-primary text-primary-foreground px-4 py-2.5"
+              : "rounded-2xl rounded-tl-sm bg-muted/70 text-foreground border border-border/40 px-4 py-2.5",
+          )}
+        >
+          {isUser ? (
+            <div className="whitespace-pre-wrap break-words">{msg.content}</div>
+          ) : (
+            <MarkdownRenderer
+              content={msg.content}
+              onOpenCodePanel={(payload) =>
+                openCodePreview({ ...payload, id: crypto.randomUUID() })
+              }
+            />
+          )}
+        </div>
+      </div>
+
+      {isUser && <UserAvatar />}
+    </div>
+  );
+});
+
+function AIAvatar({ providerName }: { providerName?: string }) {
+  const Icon = providerName ? getProviderIcon(providerName) : null;
+
+  if (Icon) {
+    return (
+      <span
+        className="mt-0.5 grid size-8 shrink-0 place-items-center rounded-full bg-gradient-to-br from-primary/15 to-primary/5 ring-1 ring-primary/10 shadow-sm"
+        aria-hidden="true"
+      >
+        <Icon className="size-4 text-primary/70" />
+      </span>
+    );
+  }
+
+  return (
+    <span
+      className="mt-0.5 grid size-8 shrink-0 place-items-center rounded-full bg-gradient-to-br from-primary/20 to-primary/5 ring-1 ring-primary/10 shadow-sm"
+      aria-hidden="true"
+    >
+      <Sparkles className="size-3.5 text-primary/60" />
+    </span>
+  );
+}
+
+function UserAvatar() {
+  return (
+    <span
+      className="mt-0.5 grid size-8 shrink-0 place-items-center rounded-full bg-gradient-to-br from-muted to-muted/50 ring-1 ring-border/40 shadow-sm"
+      aria-hidden="true"
+    >
+      <User className="size-3.5 text-muted-foreground/70" />
+    </span>
+  );
+}
diff --git a/src/page/workspace/workplan/chat/message-nav-dots.tsx b/src/page/workspace/workplan/chat/message-nav-dots.tsx
new file mode 100644
index 0000000..c1188b0
--- /dev/null
+++ b/src/page/workspace/workplan/chat/message-nav-dots.tsx
@@ -0,0 +1,185 @@
+import { memo, useEffect, useCallback, useState, useMemo } from "react";
+import { motion, AnimatePresence } from "motion/react";
+import type { Message } from "./types";
+
+interface MessageNavDotsProps {
+  messages: Message[];
+  scrollContainerRef: React.RefObject<HTMLDivElement | null>;
+}
+
+/** Elegant message timeline navigation — a visual TOC for the conversation. */
+export const MessageNavDots = memo(function MessageNavDots({
+  messages,
+  scrollContainerRef,
+}: MessageNavDotsProps) {
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+
+  const userNodes = useMemo(() => {
+    const nodes: { msgIndex: number; dotIndex: number; preview: string }[] = [];
+    let dotIdx = 0;
+    messages.forEach((m, i) => {
+      if (m.role === "user") {
+        const preview = m.content.slice(0, 36).replace(/\n/g, " ");
+        nodes.push({ msgIndex: i, dotIndex: dotIdx, preview: preview || "\u2026" });
+        dotIdx++;
+      }
+    });
+    return nodes;
+  }, [messages]);
+
+  const totalDots = userNodes.length;
+
+  // Track active index via scroll position.
+  const handleScroll = useCallback(() => {
+    const container = scrollContainerRef.current;
+    if (!container || totalDots <= 1) return;
+
+    const { scrollTop, scrollHeight, clientHeight } = container;
+    const progress =
+      scrollHeight > clientHeight
+        ? Math.max(0, Math.min(1, scrollTop / (scrollHeight - clientHeight)))
+        : 0;
+    const idx = Math.round(progress * (totalDots - 1));
+    setActiveIndex(idx);
+  }, [scrollContainerRef, totalDots]);
+
+  useEffect(() => {
+    const container = scrollContainerRef.current;
+    if (!container || totalDots <= 1) return;
+    container.addEventListener("scroll", handleScroll, { passive: true });
+    return () => container.removeEventListener("scroll", handleScroll);
+  }, [handleScroll, scrollContainerRef, totalDots]);
+
+  const handleDotClick = useCallback(
+    (dotIndex: number) => {
+      const container = scrollContainerRef.current;
+      if (!container) return;
+      const msgIndex = userNodes[dotIndex]?.msgIndex;
+      if (msgIndex === undefined) return;
+      const el = container.querySelector<HTMLElement>(
+        `[data-msg-index="${msgIndex}"]`,
+      );
+      el?.scrollIntoView({ behavior: "smooth", block: "center" });
+    },
+    [scrollContainerRef, userNodes],
+  );
+
+  // Early return AFTER all hooks to keep them stable.
+  if (totalDots <= 1) return null;
+
+  // Fill height of the active progress line.
+  const progressPct =
+    totalDots > 1 ? (activeIndex / (totalDots - 1)) * 100 : 0;
+
+  return (
+    <div
+      aria-label="Message navigation"
+      className="absolute right-2 top-4 bottom-4 z-20 flex flex-col items-center"
+      style={{ width: 40 }}
+    >
+      {/* Timeline container */}
+      <div className="relative flex flex-1 flex-col items-center justify-between py-2">
+        {/* Background track */}
+        <div className="absolute inset-y-2 left-1/2 w-px -translate-x-1/2 bg-border/40" />
+        {/* Active progress fill */}
+        <motion.div
+          className="absolute top-2 left-1/2 w-px -translate-x-1/2 bg-primary/40"
+          animate={{ height: `${progressPct}%` }}
+          initial={false}
+          transition={{ duration: 0.35, ease: "easeOut" }}
+        />
+
+        {userNodes.map(({ msgIndex, dotIndex, preview }) => {
+          const isActive = dotIndex === activeIndex;
+          const isHovered = dotIndex === hoveredIndex;
+          const isPast = dotIndex < activeIndex;
+
+          return (
+            <div
+              key={msgIndex}
+              className="relative z-10 flex items-center"
+              onMouseEnter={() => setHoveredIndex(dotIndex)}
+              onMouseLeave={() => setHoveredIndex(null)}
+            >
+              {/* Hover preview tooltip */}
+              <AnimatePresence>
+                {isHovered && (
+                  <motion.div
+                    initial={{ opacity: 0, x: 6, scale: 0.92 }}
+                    animate={{ opacity: 1, x: 0, scale: 1 }}
+                    exit={{ opacity: 0, x: 6, scale: 0.92 }}
+                    transition={{ duration: 0.18, ease: "easeOut" }}
+                    className="absolute right-8 top-1/2 -translate-y-1/2 whitespace-nowrap rounded-lg border border-border/60 bg-card/95 px-3 py-1.5 text-[11px] text-muted-foreground shadow-lg backdrop-blur-sm"
+                  >
+                    <span className="font-medium text-foreground">
+                      {dotIndex + 1}.
+                    </span>{" "}
+                    {preview}
+                    {preview.length >= 36 && "\u2026"}
+                  </motion.div>
+                )}
+              </AnimatePresence>
+
+              {/* The dot */}
+              <motion.button
+                type="button"
+                aria-label={`Jump to message ${dotIndex + 1}`}
+                onClick={() => handleDotClick(dotIndex)}
+                whileTap={{ scale: 0.85 }}
+                className="relative flex cursor-pointer items-center justify-center rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                style={{ width: 20, height: 20 }}
+              >
+                {/* Active glow ring */}
+                <AnimatePresence>
+                  {isActive && (
+                    <motion.span
+                      initial={{ scale: 0.5, opacity: 0 }}
+                      animate={{ scale: 1.6, opacity: 0.18 }}
+                      exit={{ scale: 0.5, opacity: 0 }}
+                      transition={{ duration: 0.4, ease: "easeOut" }}
+                      className="absolute inset-0 rounded-full bg-primary"
+                    />
+                  )}
+                </AnimatePresence>
+
+                {/* Dot core */}
+                <motion.span
+                  animate={{
+                    scale: isActive ? 1.15 : isHovered ? 1.05 : 1,
+                  }}
+                  initial={false}
+                  transition={{ duration: 0.25, ease: "easeOut" }}
+                  className={[
+                    "relative block rounded-full border-2 shadow-sm transition-colors",
+                    isActive && "size-3 border-primary bg-primary shadow-primary/25",
+                    isPast && !isActive && "size-2.5 border-primary/40 bg-primary/45",
+                    !isActive && !isPast && "size-2 border-muted-foreground/20 bg-muted-foreground/25",
+                    isHovered && !isActive && "border-primary/40",
+                  ]
+                    .filter(Boolean)
+                    .join(" ")}
+                />
+
+                {/* Number badge on active */}
+                <AnimatePresence>
+                  {isActive && (
+                    <motion.span
+                      initial={{ opacity: 0, scale: 0.6 }}
+                      animate={{ opacity: 1, scale: 1 }}
+                      exit={{ opacity: 0, scale: 0.6 }}
+                      transition={{ duration: 0.2, delay: 0.05 }}
+                      className="absolute -bottom-5 left-1/2 -translate-x-1/2 text-[9px] font-semibold tabular-nums text-primary/70"
+                    >
+                      {dotIndex + 1}
+                    </motion.span>
+                  )}
+                </AnimatePresence>
+              </motion.button>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+});
diff --git a/src/page/workspace/workplan/chat/model-selector-popover.tsx b/src/page/workspace/workplan/chat/model-selector-popover.tsx
new file mode 100644
index 0000000..bd34ed1
--- /dev/null
+++ b/src/page/workspace/workplan/chat/model-selector-popover.tsx
@@ -0,0 +1,205 @@
+import { useState, useEffect, useCallback, useMemo } from "react";
+import { motion } from "motion/react";
+import { cn } from "@/lib/utils";
+import { client } from "@/client";
+import type { AiModelListItem } from "@/client/models/aiModelListItem";
+import {
+  ModelSelector,
+  ModelSelectorTrigger,
+  ModelSelectorContent,
+  ModelSelectorInput,
+  ModelSelectorList,
+  ModelSelectorEmpty,
+  ModelSelectorGroup,
+  ModelSelectorItem,
+} from "@/components/ai-elements/model-selector";
+import { DialogTitle } from "@/components/ui/dialog";
+import { getModelIcon } from "./provider-icon";
+
+const STORAGE_KEY = "gitdataai:last-model-id";
+
+function loadLastModelId(sessionId?: string | null): string | null {
+  try {
+    if (sessionId) {
+      const val = localStorage.getItem(`${STORAGE_KEY}:${sessionId}`);
+      if (val) return val;
+    }
+    return localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function saveLastModelId(modelId: string, sessionId?: string | null) {
+  try {
+    localStorage.setItem(STORAGE_KEY, modelId);
+    if (sessionId) {
+      localStorage.setItem(`${STORAGE_KEY}:${sessionId}`, modelId);
+    }
+  } catch {
+    // Storage full or unavailable — non-critical.
+  }
+}
+
+interface ModelSelectorPopoverProps {
+  sessionId?: string | null;
+  onModelChange?: (name: string, provider: string) => void;
+}
+
+export function ModelSelectorPopover({
+  sessionId,
+  onModelChange,
+}: ModelSelectorPopoverProps) {
+  const [models, setModels] = useState<AiModelListItem[]>([]);
+  const [selected, setSelected] = useState<string>("");
+  const [open, setOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [initialised, setInitialised] = useState(false);
+
+  // Load model list.
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    client
+      .aiListModels()
+      .then(({ data }) => {
+        if (!cancelled) {
+          const enabled = data.filter((m) => m.enabled);
+          setModels(enabled);
+        }
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          console.error("Failed to load models:", err);
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Auto-select last-used model once models are loaded.
+  useEffect(() => {
+    if (initialised || models.length === 0) return;
+
+    const lastId = loadLastModelId(sessionId);
+    const matched = lastId ? models.find((m) => m.id === lastId) : null;
+    const chosen = matched ?? models[0];
+    if (chosen) {
+      setSelected(chosen.id);
+      onModelChange?.(chosen.name, chosen.provider_name);
+    }
+    setInitialised(true);
+  }, [models, sessionId, initialised, onModelChange]);
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      setSelected(id);
+      saveLastModelId(id, sessionId);
+      const model = models.find((m) => m.id === id);
+      if (model) onModelChange?.(model.name, model.provider_name);
+      setOpen(false);
+    },
+    [models, sessionId, onModelChange],
+  );
+
+  const selectedModel = models.find((m) => m.id === selected);
+  const displayName =
+    selectedModel?.display_name || selectedModel?.name || "Select model";
+
+  const ProviderIcon = useMemo(
+    () => getModelIcon(selectedModel?.name ?? "", selectedModel?.provider_name),
+    [selectedModel?.name, selectedModel?.provider_name],
+  );
+
+  return (
+    <ModelSelector open={open} onOpenChange={setOpen}>
+      <ModelSelectorTrigger
+        className={cn(
+          "flex cursor-pointer items-center gap-1.5 rounded-lg border border-border/60 bg-muted/40 px-2.5 py-1.5 text-xs text-muted-foreground transition-all",
+          "hover:bg-muted/70 hover:text-foreground hover:border-border/80 hover:shadow-sm",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        )}
+        aria-label={`Select model (current: ${displayName})`}
+      >
+        {ProviderIcon ? (
+          <ProviderIcon className="size-3.5 shrink-0 text-muted-foreground/60" />
+        ) : (
+          <div className="grid size-3.5 shrink-0 place-items-center rounded-full bg-gradient-to-br from-primary/20 to-primary/10">
+            <div className="size-1.5 rounded-full bg-primary/50" />
+          </div>
+        )}
+        <span className="max-w-[120px] truncate font-medium">{displayName}</span>
+      </ModelSelectorTrigger>
+
+      <ModelSelectorContent title="Choose a model">
+        <DialogTitle className="sr-only">Choose a model</DialogTitle>
+        <ModelSelectorInput placeholder="Search models…" />
+        <ModelSelectorList>
+          <ModelSelectorEmpty>
+            {loading ? (
+              <span className="flex items-center gap-2 text-muted-foreground/50">
+                <span className="relative flex size-2">
+                  <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-primary/30 opacity-75" />
+                  <span className="relative inline-flex size-2 rounded-full bg-primary/40" />
+                </span>
+                Loading models…
+              </span>
+            ) : (
+              "No models found"
+            )}
+          </ModelSelectorEmpty>
+          <ModelSelectorGroup>
+            {models.map((m) => {
+              const ModelIcon = getModelIcon(m.name, m.provider_name);
+              const isSelected = m.id === selected;
+              return (
+                <ModelSelectorItem
+                  key={m.id}
+                  className={cn(
+                    "flex items-center gap-2.5 rounded-lg px-3 py-2 transition-colors",
+                    isSelected && "bg-primary/[0.08]",
+                  )}
+                  onSelect={() => handleSelect(m.id)}
+                >
+                  {ModelIcon ? (
+                    <ModelIcon
+                      className={cn(
+                        "size-4 shrink-0",
+                        isSelected ? "text-primary/80" : "text-muted-foreground/50",
+                      )}
+                    />
+                  ) : (
+                    <div className="grid size-4 shrink-0 place-items-center rounded-full bg-gradient-to-br from-primary/15 to-primary/5">
+                      <div className="size-1.5 rounded-full bg-primary/40" />
+                    </div>
+                  )}
+                  <span
+                    className={cn(
+                      "flex-1 truncate text-sm",
+                      isSelected ? "font-medium text-foreground" : "text-muted-foreground",
+                    )}
+                  >
+                    {m.display_name || m.name}
+                  </span>
+                  <span className="shrink-0 text-[10px] text-muted-foreground/50">
+                    {m.provider_name}
+                  </span>
+                  {isSelected && (
+                    <motion.span
+                      layoutId="model-check"
+                      className="ml-1 inline-flex size-1.5 rounded-full bg-primary"
+                    />
+                  )}
+                </ModelSelectorItem>
+              );
+            })}
+          </ModelSelectorGroup>
+        </ModelSelectorList>
+      </ModelSelectorContent>
+    </ModelSelector>
+  );
+}
diff --git a/src/page/workspace/workplan/chat/provider-icon.tsx b/src/page/workspace/workplan/chat/provider-icon.tsx
new file mode 100644
index 0000000..a9e3190
--- /dev/null
+++ b/src/page/workspace/workplan/chat/provider-icon.tsx
@@ -0,0 +1,133 @@
+import type { ComponentType, SVGProps } from "react";
+import OpenAI from "@lobehub/icons/es/OpenAI";
+import Anthropic from "@lobehub/icons/es/Anthropic";
+import Google from "@lobehub/icons/es/Google";
+import Gemini from "@lobehub/icons/es/Gemini";
+import DeepSeek from "@lobehub/icons/es/DeepSeek";
+import Meta from "@lobehub/icons/es/Meta";
+import Mistral from "@lobehub/icons/es/Mistral";
+import Claude from "@lobehub/icons/es/Claude";
+import Qwen from "@lobehub/icons/es/Qwen";
+import Zhipu from "@lobehub/icons/es/Zhipu";
+import ChatGLM from "@lobehub/icons/es/ChatGLM";
+import Kimi from "@lobehub/icons/es/Kimi";
+import Minimax from "@lobehub/icons/es/Minimax";
+import Moonshot from "@lobehub/icons/es/Moonshot";
+import Stepfun from "@lobehub/icons/es/Stepfun";
+import Yi from "@lobehub/icons/es/Yi";
+import Doubao from "@lobehub/icons/es/Doubao";
+import ByteDance from "@lobehub/icons/es/ByteDance";
+import Baidu from "@lobehub/icons/es/Baidu";
+import Hunyuan from "@lobehub/icons/es/Hunyuan";
+import Tencent from "@lobehub/icons/es/Tencent";
+import Spark from "@lobehub/icons/es/Spark";
+import Baichuan from "@lobehub/icons/es/Baichuan";
+
+type LobeIcon = ComponentType<SVGProps<SVGSVGElement>>;
+
+/** Prefix rules for matching model IDs to icons. First match wins. */
+const MODEL_PREFIXES: Array<[string, LobeIcon]> = [
+  // OpenAI
+  ["gpt-", OpenAI],
+  ["o1-", OpenAI],
+  ["o3-", OpenAI],
+  ["o4-", OpenAI],
+  ["chatgpt-", OpenAI],
+  // Anthropic / Claude
+  ["claude-", Claude],
+  ["anthropic-", Anthropic],
+  // Google
+  ["gemini-", Gemini],
+  ["gemma-", Google],
+  ["palm-", Google],
+  // DeepSeek
+  ["deepseek-", DeepSeek],
+  // Meta
+  ["llama-", Meta],
+  ["meta-", Meta],
+  // Mistral
+  ["mistral-", Mistral],
+  ["codestral-", Mistral],
+  ["mixtral-", Mistral],
+  // Alibaba
+  ["qwen-", Qwen],
+  ["tongyi-", Qwen],
+  // Zhipu / GLM
+  ["glm-", Zhipu],
+  ["zhipu-", Zhipu],
+  ["chatglm-", ChatGLM],
+  // Moonshot / Kimi
+  ["kimi-", Kimi],
+  ["moonshot-", Moonshot],
+  // MiniMax
+  ["minimax-", Minimax],
+  ["abab-", Minimax],
+  // Stepfun
+  ["step-", Stepfun],
+  // 01.AI / Yi
+  ["yi-", Yi],
+  // ByteDance / Doubao
+  ["doubao-", Doubao],
+  ["skylark-", ByteDance],
+  // Baidu
+  ["ernie-", Baidu],
+  ["baidu-", Baidu],
+  // Tencent
+  ["hunyuan-", Hunyuan],
+  ["tencent-", Tencent],
+  // iFlytek
+  ["spark-", Spark],
+  ["iflytek-", Spark],
+  // Baichuan
+  ["baichuan-", Baichuan],
+];
+
+/** Provider name → icon (case-insensitive key). */
+const PROVIDER_ICONS: Record<string, LobeIcon> = {
+  openai: OpenAI,
+  anthropic: Anthropic,
+  google: Google,
+  gemini: Gemini,
+  deepseek: DeepSeek,
+  meta: Meta,
+  mistral: Mistral,
+  claude: Claude,
+  qwen: Qwen,
+  zhipu: Zhipu,
+  glm: Zhipu,
+  chatglm: ChatGLM,
+  kimi: Kimi,
+  minimax: Minimax,
+  moonshot: Moonshot,
+  stepfun: Stepfun,
+  yi: Yi,
+  doubao: Doubao,
+  bytedance: ByteDance,
+  baidu: Baidu,
+  hunyuan: Hunyuan,
+  tencent: Tencent,
+  spark: Spark,
+  iflytek: Spark,
+  baichuan: Baichuan,
+};
+
+export function getModelIcon(
+  modelName: string,
+  providerName?: string,
+): LobeIcon | null {
+  const lower = modelName.toLowerCase().trim();
+  for (const [prefix, icon] of MODEL_PREFIXES) {
+    if (lower.startsWith(prefix)) return icon;
+  }
+  if (providerName) return getProviderIcon(providerName);
+  return null;
+}
+
+export function getProviderIcon(providerName: string): LobeIcon | null {
+  const key = providerName.toLowerCase().trim();
+  if (PROVIDER_ICONS[key]) return PROVIDER_ICONS[key];
+  for (const [k, icon] of Object.entries(PROVIDER_ICONS)) {
+    if (key.includes(k)) return icon;
+  }
+  return null;
+}
diff --git a/src/page/workspace/workplan/chat/streaming-view.tsx b/src/page/workspace/workplan/chat/streaming-view.tsx
new file mode 100644
index 0000000..442f45e
--- /dev/null
+++ b/src/page/workspace/workplan/chat/streaming-view.tsx
@@ -0,0 +1,225 @@
+import { memo, useCallback } from "react";
+import { motion } from "motion/react";
+import { Sparkles } from "lucide-react";
+import {
+  Reasoning,
+  ReasoningTrigger,
+  ReasoningContent,
+} from "@/components/ai-elements/reasoning";
+import {
+  Tool,
+  ToolHeader,
+  ToolContent,
+  ToolInput,
+  ToolOutput,
+} from "@/components/ai-elements/tool";
+import { Shimmer } from "@/components/ai-elements/shimmer";
+import { MarkdownRenderer } from "@/components/MarkdownRenderer";
+import { getProviderIcon } from "./provider-icon";
+import { isVisibleToolCall } from "./tool-utils";
+import type { StreamingState } from "./types";
+
+// ---- Helpers ----
+
+function parseToolArguments(
+  args: string,
+): Record<string, unknown> | string {
+  try {
+    return JSON.parse(args) as Record<string, unknown>;
+  } catch {
+    return args;
+  }
+}
+
+const parsedArgsCache = new Map<string, Record<string, unknown> | string>();
+function parseToolArgumentsCached(
+  args: string,
+): Record<string, unknown> | string {
+  const cached = parsedArgsCache.get(args);
+  if (cached !== undefined) return cached;
+  const result = parseToolArguments(args);
+  parsedArgsCache.set(args, result);
+  return result;
+}
+
+// ---- Component ----
+
+export const StreamingView = memo(function StreamingView({
+  stream,
+  modelProvider,
+}: {
+  stream: StreamingState;
+  modelProvider?: string;
+}) {
+  const { phase, thinkText, answerText, toolCalls } = stream;
+
+  const isFinal =
+    phase === "summarize" || phase === "completed" || phase === "idle";
+  const showCursor = !isFinal && answerText.length > 0;
+
+  const showInitialLoading =
+    phase === "idle" &&
+    !answerText &&
+    !thinkText &&
+    toolCalls.length === 0;
+
+  const thinkingMessage = useCallback(
+    (streaming: boolean, duration?: number) => (
+      <span className="flex items-center gap-2">
+        {streaming ? (
+          <span className="flex items-center gap-1.5">
+            <span className="relative flex size-2">
+              <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-primary/40 opacity-75" />
+              <span className="relative inline-flex size-2 rounded-full bg-primary/60" />
+            </span>
+            <span>Thinking</span>
+          </span>
+        ) : duration != null ? (
+          <span>Thought for {duration}s</span>
+        ) : (
+          <span>Thinking</span>
+        )}
+      </span>
+    ),
+    [],
+  );
+
+  return (
+    <div className="space-y-3" role="status" aria-live="polite">
+      {/* Thinking content */}
+      {thinkText && (
+        <Reasoning isStreaming={phase === "think"}>
+          <ReasoningTrigger getThinkingMessage={thinkingMessage} />
+          <ReasoningContent>{thinkText}</ReasoningContent>
+        </Reasoning>
+      )}
+
+      {/* Tool calls */}
+      {toolCalls
+        .filter((tc) => isVisibleToolCall(tc.toolName))
+        .map((tc) => (
+          <Tool key={tc.toolCallId}>
+            <ToolHeader
+              type="dynamic-tool"
+              state={
+                tc.error
+                  ? "output-error"
+                  : tc.output != null
+                    ? "output-available"
+                    : "input-streaming"
+              }
+              title={tc.toolName}
+              toolName={tc.toolName}
+            />
+            <ToolContent>
+              {tc.arguments && (
+                <ToolInput input={parseToolArgumentsCached(tc.arguments)} />
+              )}
+              {(tc.output || tc.error) && (
+                <ToolOutput
+                  output={tc.output ?? undefined}
+                  errorText={tc.error ?? undefined}
+                />
+              )}
+            </ToolContent>
+          </Tool>
+        ))}
+
+      {/* Answer text */}
+      {answerText && (
+        <AnswerBubble
+          content={answerText}
+          showCursor={showCursor}
+          providerName={modelProvider}
+        />
+      )}
+
+      {/* Initial connecting state */}
+      {showInitialLoading && <ConnectingState providerName={modelProvider} />}
+    </div>
+  );
+});
+
+// ---- Sub-components ----
+
+const AnswerBubble = memo(function AnswerBubble({
+  content,
+  showCursor,
+  providerName,
+}: {
+  content: string;
+  showCursor: boolean;
+  providerName?: string;
+}) {
+  const Icon = providerName ? getProviderIcon(providerName) : null;
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 6 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.25, ease: "easeOut" }}
+      className="flex gap-3"
+    >
+      <AIAvatarStreaming Icon={Icon} />
+      <div className="max-w-[85%] space-y-2">
+        <div className="relative overflow-hidden rounded-2xl rounded-tl-sm border border-border/40 bg-muted/70 px-4 py-2.5 text-sm leading-relaxed text-foreground shadow-sm">
+          <MarkdownRenderer
+            content={showCursor ? content + "\u25CA" : content}
+          />
+          {showCursor && (
+            <span className="ml-0.5 inline-block h-4 w-px animate-pulse bg-primary/60 align-middle" />
+          )}
+        </div>
+      </div>
+    </motion.div>
+  );
+});
+
+const ConnectingState = memo(function ConnectingState({
+  providerName,
+}: {
+  providerName?: string;
+}) {
+  const Icon = providerName ? getProviderIcon(providerName) : null;
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 6 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.25, ease: "easeOut" }}
+      className="flex gap-3"
+    >
+      <AIAvatarStreaming Icon={Icon} />
+      <div className="rounded-2xl rounded-tl-sm border border-border/40 bg-muted/70 px-4 py-2.5 text-sm shadow-sm">
+        <span className="flex items-center gap-2">
+          <span className="relative flex size-2">
+            <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-primary/40 opacity-75" />
+            <span className="relative inline-flex size-2 rounded-full bg-primary/60" />
+          </span>
+          <Shimmer duration={1.5} spread={2}>
+            Connecting to AI agent…
+          </Shimmer>
+        </span>
+      </div>
+    </motion.div>
+  );
+});
+
+function AIAvatarStreaming({
+  Icon,
+}: {
+  Icon: React.ComponentType<React.SVGProps<SVGSVGElement>> | null;
+}) {
+  return (
+    <span
+      className="mt-0.5 grid size-8 shrink-0 place-items-center rounded-full bg-gradient-to-br from-primary/15 to-primary/5 ring-1 ring-primary/10 shadow-sm"
+      aria-hidden="true"
+    >
+      {Icon ? (
+        <Icon className="size-4 text-primary/70" />
+      ) : (
+        <Sparkles className="size-3.5 text-primary/60" />
+      )}
+    </span>
+  );
+}
diff --git a/src/page/workspace/workplan/chat/tool-call-list.tsx b/src/page/workspace/workplan/chat/tool-call-list.tsx
new file mode 100644
index 0000000..abd5860
--- /dev/null
+++ b/src/page/workspace/workplan/chat/tool-call-list.tsx
@@ -0,0 +1,241 @@
+import { memo, useState } from "react";
+import { motion, AnimatePresence } from "motion/react";
+
+import {
+  ChevronDown,
+  Bot,
+  CheckCircle2,
+  XCircle,
+  Loader2,
+} from "lucide-react";
+import {
+  Tool,
+  ToolHeader,
+  ToolContent,
+  ToolInput,
+  ToolOutput,
+} from "@/components/ai-elements/tool";
+import type { ToolCallRecord } from "./types";
+
+/**
+ * Collapsible tool call list — uses ai-elements Tool components
+ * for regular tools and SubAgentCard for subagent calls.
+ */
+export const ToolCallList = memo(function ToolCallList({
+  toolCalls,
+  isStreaming = false,
+}: {
+  toolCalls: ToolCallRecord[];
+  isStreaming?: boolean;
+}) {
+  if (toolCalls.length === 0) return null;
+
+  return (
+    <div className="space-y-2">
+      {toolCalls.map((tc) => {
+        const isSubAgent = tc.name === "call_sub_agent";
+        if (isSubAgent) {
+          return (
+            <SubAgentCard key={tc.id} toolCall={tc} isStreaming={isStreaming} />
+          );
+        }
+        return (
+          <RegularToolCard key={tc.id} toolCall={tc} isStreaming={isStreaming} />
+        );
+      })}
+    </div>
+  );
+});
+
+/** SubAgent — compact card with role, task, output preview. */
+const SubAgentCard = memo(function SubAgentCard({
+  toolCall,
+  isStreaming,
+}: {
+  toolCall: ToolCallRecord;
+  isStreaming: boolean;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const role = (toolCall.arguments as Record<string, unknown>)?.role as
+    | string
+    | undefined;
+  const task = (toolCall.arguments as Record<string, unknown>)?.task as
+    | string
+    | undefined;
+  const hasOutput =
+    typeof toolCall.output === "object" && toolCall.output !== null;
+  const outputText = hasOutput
+    ? JSON.stringify(toolCall.output, null, 2)
+    : typeof toolCall.output === "string"
+      ? toolCall.output
+      : "";
+  const lineCount = outputText ? outputText.split("\n").length : 0;
+  const isPending = !toolCall.output && !toolCall.error && isStreaming;
+  const isOk = !!toolCall.output && !toolCall.error;
+  const isError = !!toolCall.error;
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 4 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.2 }}
+      className="overflow-hidden rounded-xl border border-border/50 bg-card/80 shadow-sm"
+    >
+      {/* Header */}
+      <button
+        className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left transition-colors hover:bg-muted/20"
+        onClick={() => setExpanded(!expanded)}
+        type="button"
+      >
+        {/* Status icon */}
+        <span className="shrink-0">
+          {isPending ? (
+            <Loader2 className="size-3.5 animate-spin text-blue-500" />
+          ) : isOk ? (
+            <CheckCircle2 className="size-3.5 text-emerald-500" />
+          ) : isError ? (
+            <XCircle className="size-3.5 text-destructive" />
+          ) : (
+            <Bot className="size-3.5 text-muted-foreground/40" />
+          )}
+        </span>
+
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2">
+            <span className="text-[13px] font-medium text-foreground">
+              {role || "Sub-agent"}
+            </span>
+            <span className="rounded-md bg-muted/70 px-1.5 py-[2px] text-[10px] font-medium text-muted-foreground/70">
+              sub-agent
+            </span>
+          </div>
+          {task && (
+            <p className="mt-0.5 line-clamp-1 text-[11px] text-muted-foreground/60">
+              {task}
+            </p>
+          )}
+        </div>
+
+        {/* Expand chevron */}
+        <motion.span
+          animate={{ rotate: expanded ? 180 : 0 }}
+          transition={{ duration: 0.2 }}
+          className="shrink-0 text-muted-foreground/40"
+        >
+          <ChevronDown className="size-3.5" />
+        </motion.span>
+      </button>
+
+      {/* Output preview (collapsed) */}
+      <AnimatePresence>
+        {!expanded && outputText && (
+          <motion.div
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: "auto", opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={{ duration: 0.2 }}
+            className="overflow-hidden border-t border-border/30"
+          >
+            <div className="px-3 pb-3 pt-2.5">
+              <pre className="max-h-24 overflow-hidden rounded-lg border border-border/30 bg-muted/25 px-3 py-2 text-[11px] leading-relaxed text-muted-foreground/70">
+                <code>{outputText.slice(0, 500)}</code>
+                {outputText.length > 500 && (
+                  <span className="text-muted-foreground/30"> …</span>
+                )}
+              </pre>
+              {lineCount > 0 && (
+                <div className="mt-1.5 flex items-center gap-1 text-[10px] text-muted-foreground/35">
+                  <span>{lineCount} lines</span>
+                  <span>·</span>
+                  <span>click to expand</span>
+                </div>
+              )}
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      {/* Expanded content */}
+      <AnimatePresence>
+        {expanded && (
+          <motion.div
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: "auto", opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={{ duration: 0.25 }}
+            className="overflow-hidden border-t border-border/30"
+          >
+            <div className="space-y-3 px-3 pb-3 pt-2.5">
+              {task && (
+                <div>
+                  <div className="mb-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground/50">
+                    Task
+                  </div>
+                  <div className="rounded-lg bg-muted/25 px-3 py-2 text-[12px] text-foreground/80">
+                    {task}
+                  </div>
+                </div>
+              )}
+              {outputText && (
+                <div>
+                  <div className="mb-1 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground/50">
+                    Output
+                  </div>
+                  <pre className="max-h-72 overflow-auto rounded-lg border border-border/30 bg-muted/25 px-3 py-2 text-[11px] leading-relaxed text-muted-foreground/80">
+                    <code>{outputText}</code>
+                  </pre>
+                </div>
+              )}
+              {toolCall.error && (
+                <div>
+                  <div className="mb-1 text-[10px] font-semibold uppercase tracking-wider text-destructive/60">
+                    Error
+                  </div>
+                  <div className="rounded-lg bg-destructive/[0.06] px-3 py-2 text-[12px] text-destructive/80">
+                    {toolCall.error}
+                  </div>
+                </div>
+              )}
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </motion.div>
+  );
+});
+
+/** Regular tool — uses ai-elements Tool compound component. */
+const RegularToolCard = memo(function RegularToolCard({
+  toolCall,
+}: {
+  toolCall: ToolCallRecord;
+  isStreaming: boolean;
+}) {
+  return (
+    <Tool>
+      <ToolHeader
+        type="dynamic-tool"
+        state={
+          toolCall.error
+            ? "output-error"
+            : toolCall.output != null
+              ? "output-available"
+              : "input-streaming"
+        }
+        title={toolCall.name}
+        toolName={toolCall.name}
+      />
+      <ToolContent>
+        {toolCall.arguments && Object.keys(toolCall.arguments).length > 0 && (
+          <ToolInput input={toolCall.arguments} />
+        )}
+        {(toolCall.output || toolCall.error) && (
+          <ToolOutput
+            output={toolCall.output ?? undefined}
+            errorText={toolCall.error ?? undefined}
+          />
+        )}
+      </ToolContent>
+    </Tool>
+  );
+});
diff --git a/src/page/workspace/workplan/chat/tool-utils.ts b/src/page/workspace/workplan/chat/tool-utils.ts
new file mode 100644
index 0000000..45ae872
--- /dev/null
+++ b/src/page/workspace/workplan/chat/tool-utils.ts
@@ -0,0 +1,9 @@
+/** Internal tool names that should not be rendered in the UI. */
+const HIDDEN_TOOLS = new Set([
+  "set_conversation_title",
+  "save_memory",
+]);
+
+export function isVisibleToolCall(toolName: string): boolean {
+  return !HIDDEN_TOOLS.has(toolName);
+}
diff --git a/src/page/workspace/workplan/chat/types.ts b/src/page/workspace/workplan/chat/types.ts
new file mode 100644
index 0000000..ce2c227
--- /dev/null
+++ b/src/page/workspace/workplan/chat/types.ts
@@ -0,0 +1,51 @@
+export interface Message {
+  id: string;
+  conversation_id: string;
+  role: "user" | "assistant";
+  content: string;
+  content_type: "text";
+  reasoning_content?: string | null;
+  tool_calls?: ToolCallRecord[];
+  created_at: string;
+}
+
+export interface ToolCallRecord {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  output?: Record<string, unknown> | null;
+  error?: string | null;
+  status: string;
+  elapsed_ms?: number | null;
+}
+
+export interface Conversation {
+  id: string;
+  title: string;
+  session_id: string;
+}
+
+export type Phase = "idle" | "think" | "answer" | "act" | "summarize" | "completed";
+
+export interface ToolCallState {
+  toolCallId: string;
+  toolName: string;
+  arguments: string;
+  output?: string;
+  error?: string | null;
+}
+
+export interface StreamingState {
+  phase: Phase;
+  thinkText: string;
+  answerText: string;
+  toolCalls: ToolCallState[];
+}
+
+/** Empty streaming state used for resetting. */
+export const EMPTY_STREAM: StreamingState = {
+  phase: "idle",
+  thinkText: "",
+  answerText: "",
+  toolCalls: [],
+};
diff --git a/src/page/workspace/workplan/chat/use-session.ts b/src/page/workspace/workplan/chat/use-session.ts
new file mode 100644
index 0000000..7bb6533
--- /dev/null
+++ b/src/page/workspace/workplan/chat/use-session.ts
@@ -0,0 +1,35 @@
+import { client } from "@/client";
+import type { AgentSessionResponse } from "@/client/models/agentSessionResponse";
+
+/**
+ * Find an existing workspace session or create one.
+ * Returns the session ID, or null if creation fails.
+ */
+export async function ensureWorkspaceSession(
+  projectName: string,
+  existingSessions: AgentSessionResponse[],
+): Promise<string | null> {
+  // Reuse existing workspace session if available.
+  const wsSession = existingSessions.find(
+    (s) => s.enabled && s.wk != null && s.wk !== "",
+  );
+  if (wsSession) return wsSession.id;
+
+  // Create a new session scoped to this workspace.
+  try {
+    const modelsRes = await client.aiListModels();
+    const modelVersion = modelsRes.data[0]?.id;
+    if (!modelVersion) return null;
+
+    const res = await client.agentCreateSession({
+      name: `${projectName} Agent`,
+      agent_kind: "chat",
+      model_version: modelVersion,
+      wk: projectName,
+      visibility: "workspace",
+    });
+    return res.data.id;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/page/workspace/workplan/chat/use-sessions.ts b/src/page/workspace/workplan/chat/use-sessions.ts
new file mode 100644
index 0000000..b67a432
--- /dev/null
+++ b/src/page/workspace/workplan/chat/use-sessions.ts
@@ -0,0 +1,46 @@
+import { useState, useEffect, useRef, useCallback } from "react";
+import { client } from "@/client";
+import type { AgentSessionResponse } from "@/client/models/agentSessionResponse";
+
+/**
+ * Shared hook: load and cache workspace sessions.
+ * Used by both ChatSidebar and ChatList to avoid duplicate API calls.
+ */
+export function useWorkspaceSessions(projectName: string) {
+  const [sessions, setSessions] = useState<AgentSessionResponse[]>([]);
+  const [loading, setLoading] = useState(true);
+  const sessionsRef = useRef<AgentSessionResponse[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    client
+      .agentListSessions()
+      .then(({ data }) => {
+        if (!cancelled) {
+          const filtered = data.filter(
+            (s) => s.enabled && s.wk != null && s.wk !== "",
+          );
+          sessionsRef.current = filtered;
+          setSessions(filtered);
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [projectName]);
+
+  const addSession = useCallback((session: AgentSessionResponse) => {
+    setSessions((prev) => {
+      const exists = prev.some((s) => s.id === session.id);
+      if (exists) return prev;
+      return [...prev, session];
+    });
+  }, []);
+
+  return { sessions, loading, sessionsRef, addSession };
+}
diff --git a/src/page/workspace/workplan/chat/utils.ts b/src/page/workspace/workplan/chat/utils.ts
new file mode 100644
index 0000000..2e7a54d
--- /dev/null
+++ b/src/page/workspace/workplan/chat/utils.ts
@@ -0,0 +1,21 @@
+const MAX_TITLE_LENGTH = 28;
+
+export function formatTime(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffDays = Math.floor(diffMs / 86_400_000);
+
+  if (diffDays === 0) {
+    return d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  }
+  if (diffDays === 1) return "Yesterday";
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return d.toLocaleDateString([], { month: "short", day: "numeric" });
+}
+
+export function truncateTitle(title: string): string {
+  if (title.length <= MAX_TITLE_LENGTH) return title;
+  return title.slice(0, MAX_TITLE_LENGTH) + "\u2026";
+}
diff --git a/src/socket/dedup.ts b/src/socket/dedup.ts
new file mode 100644
index 0000000..ed2ae80
--- /dev/null
+++ b/src/socket/dedup.ts
@@ -0,0 +1,40 @@
+/**
+ * Client-side deduplication manager for WebSocket events.
+ * Prevents duplicate message display when the same event is delivered
+ * via both WebSocket broadcast and HTTP response.
+ *
+ * Uses a Set + insertion-order queue for predictable LRU eviction.
+ */
+export class DedupManager {
+  private seen = new Set<string>();
+  private order: string[] = [];
+  private readonly maxSize: number;
+
+  constructor(maxSize = 5000) {
+    this.maxSize = maxSize;
+  }
+
+  /** Returns true if this event was already seen (duplicate). */
+  checkAndMark(messageId: string, roomId: string): boolean {
+    const key = `${roomId}:${messageId}`;
+    if (this.seen.has(key)) return true;
+    this.seen.add(key);
+    this.order.push(key);
+    // Evict oldest entries when over limit — remove in batches of 500
+    if (this.order.length > this.maxSize) {
+      const removeCount = this.order.length - this.maxSize + 500;
+      const batch = this.order.splice(0, removeCount);
+      for (const k of batch) this.seen.delete(k);
+    }
+    return false;
+  }
+
+  clear(): void {
+    this.seen.clear();
+    this.order = [];
+  }
+
+  destroy(): void {
+    this.clear();
+  }
+}
diff --git a/src/socket/fallback.ts b/src/socket/fallback.ts
new file mode 100644
index 0000000..44013a1
--- /dev/null
+++ b/src/socket/fallback.ts
@@ -0,0 +1,322 @@
+import type { AxiosInstance, AxiosRequestConfig, Method } from "axios";
+
+import { api } from "@/client";
+
+import type { ChannelMessage } from "./types";
+
+type HttpRoute = {
+  method: Method;
+  path: string;
+  data?: unknown;
+  params?: Record<string, unknown>;
+};
+
+const defaultBasePath = "/api/v1/ws";
+
+export class ChannelHttpFallback {
+  private readonly client: AxiosInstance;
+  private readonly basePath: string;
+
+  constructor(client: AxiosInstance = api, basePath = defaultBasePath) {
+    this.client = client;
+    this.basePath = basePath.replace(/\/$/, "");
+  }
+
+  async request<T>(message: ChannelMessage): Promise<T> {
+    const route = this.toRoute(message);
+    const config: AxiosRequestConfig = {
+      method: route.method,
+      url: `${this.basePath}${route.path}`,
+      params: route.params,
+      data: route.data,
+    };
+    const response = await this.client.request<T>(config);
+    return response.data;
+  }
+
+  private toRoute(message: ChannelMessage): HttpRoute {
+    const room = enc(message.room);
+    const user = enc(message.user);
+    const msg = enc(message.message);
+    const id = enc(message.id);
+    const workspace = enc(message.workspace);
+    const threadId = enc(message.thread_id);
+    const username = enc(message.username);
+    const agentId = enc(message.agent_id);
+
+    switch (message.type) {
+      case "ping":
+        return { method: "GET", path: "/ping" };
+      case "csrf_token":
+        return { method: "GET", path: "/csrf" };
+      case "subscribe":
+        return { method: "POST", path: `/rooms/${room}/subscribe` };
+      case "unsubscribe":
+        return { method: "DELETE", path: `/rooms/${room}/subscribe` };
+      case "typing_start":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/typing`,
+          data: { action: "Start" },
+        };
+      case "typing_stop":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/typing`,
+          data: { action: "Stop" },
+        };
+      case "read_receipt":
+      case "state_set_read_seq":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/read-receipt`,
+          data: { last_read_seq: message.last_read_seq },
+        };
+      case "message_list":
+        return {
+          method: "GET",
+          path: `/rooms/${room}/messages`,
+          params: pick(message, ["before_seq", "after_seq", "limit"]),
+        };
+      case "message_around":
+        return {
+          method: "GET",
+          path: `/rooms/${room}/messages/around`,
+          params: pick(message, ["seq", "limit"]),
+        };
+      case "missed_messages":
+        return {
+          method: "GET",
+          path: `/rooms/${room}/messages/missed`,
+          params: pick(message, ["after_seq", "limit"]),
+        };
+      case "message_create":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/messages`,
+          data: pick(message, [
+            "content",
+            "content_type",
+            "thread",
+            "in_reply_to",
+          ]),
+        };
+      case "message_update":
+        return {
+          method: "PATCH",
+          path: `/messages/${msg}`,
+          data: { content: message.content },
+        };
+      case "message_revoke":
+        return { method: "DELETE", path: `/messages/${msg}` };
+      case "room_get":
+        return { method: "GET", path: `/rooms/${room}` };
+      case "room_create":
+        return {
+          method: "POST",
+          path: "/rooms",
+          data: pick(message, ["workspace", "room_name", "public", "category"]),
+        };
+      case "room_update":
+        return {
+          method: "PATCH",
+          path: `/rooms/${room}`,
+          data: pick(message, ["room_name", "public", "category"]),
+        };
+      case "room_delete":
+        return { method: "DELETE", path: `/rooms/${room}` };
+      case "category_create":
+        return {
+          method: "POST",
+          path: `/workspaces/${workspace}/categories`,
+          data: pick(message, ["name", "position"]),
+        };
+      case "category_update":
+        return {
+          method: "PATCH",
+          path: `/categories/${id}`,
+          data: pick(message, ["name", "position"]),
+        };
+      case "category_delete":
+        return { method: "DELETE", path: `/categories/${id}` };
+      case "access_grant":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/members`,
+          data: { user: message.user },
+        };
+      case "access_revoke":
+        return {
+          method: "DELETE",
+          path: `/rooms/${room}/members/${user}`,
+        };
+      case "state_update_dnd":
+        return {
+          method: "PATCH",
+          path: `/rooms/${room}/dnd`,
+          data: pick(message, [
+            "do_not_disturb",
+            "dnd_start_hour",
+            "dnd_end_hour",
+          ]),
+        };
+      case "reaction_add":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/reactions`,
+          data: pick(message, ["message", "emoji"]),
+        };
+      case "reaction_remove":
+        return {
+          method: "DELETE",
+          path: `/rooms/${room}/reactions`,
+          data: pick(message, ["message", "emoji"]),
+        };
+      case "thread_create":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/threads`,
+          data: { parent: message.parent },
+        };
+      case "thread_resolve":
+        return { method: "PATCH", path: `/threads/${threadId}/resolve` };
+      case "thread_archive":
+        return { method: "PATCH", path: `/threads/${threadId}/archive` };
+      case "pin_add":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/pins`,
+          data: { message: message.message },
+        };
+      case "pin_remove":
+        return {
+          method: "DELETE",
+          path: `/rooms/${room}/pins`,
+          data: { message: message.message },
+        };
+      case "draft_save":
+        return {
+          method: "PUT",
+          path: `/rooms/${room}/drafts`,
+          data: { content: message.content },
+        };
+      case "draft_clear":
+        return { method: "DELETE", path: `/rooms/${room}/drafts` };
+      case "search":
+        return {
+          method: "GET",
+          path: "/search",
+          params: pick(message, ["q", "room", "limit", "offset"]),
+        };
+      case "notification_mark_read":
+        return { method: "PATCH", path: `/notifications/${id}/read` };
+      case "notification_mark_all_read":
+        return {
+          method: "POST",
+          path: "/notifications/read-all",
+          data: { workspace_id: message.workspace_id },
+        };
+      case "notification_archive":
+        return { method: "DELETE", path: `/notifications/${id}` };
+      case "presence_update":
+        return {
+          method: "POST",
+          path: "/presence",
+          data: { status: message.status },
+        };
+      case "custom_status_update":
+        return {
+          method: "POST",
+          path: "/custom-status",
+          data: pick(message, ["emoji", "text", "expires_at"]),
+        };
+      case "invite_create":
+        return {
+          method: "POST",
+          path: "/invites",
+          data: pick(message, ["workspace", "room", "max_uses", "expires_at"]),
+        };
+      case "invite_accept":
+        return {
+          method: "POST",
+          path: "/invites/accept",
+          data: { code: message.code },
+        };
+      case "invite_revoke":
+        return { method: "DELETE", path: `/invites/${id}` };
+      case "ban_create":
+        return {
+          method: "POST",
+          path: `/workspaces/${workspace}/bans`,
+          data: pick(message, ["user", "reason", "expires_at"]),
+        };
+      case "ban_remove":
+        return {
+          method: "DELETE",
+          path: `/workspaces/${workspace}/bans/${user}`,
+        };
+      case "voice_join":
+        return { method: "POST", path: `/rooms/${room}/voice/join` };
+      case "voice_leave":
+        return { method: "POST", path: `/rooms/${room}/voice/leave` };
+      case "voice_mute":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/voice/mute`,
+          data: { muted: message.muted },
+        };
+      case "voice_deaf":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/voice/deaf`,
+          data: { deafened: message.deafened },
+        };
+      case "screen_share":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/screen-share`,
+          data: { start: message.start },
+        };
+      case "ai_list":
+        return { method: "GET", path: `/rooms/${room}/ai` };
+      case "ai_upsert":
+        return {
+          method: "POST",
+          path: `/rooms/${room}/ai`,
+          data: { agent_session: message.model },
+        };
+      case "ai_delete":
+        return {
+          method: "DELETE",
+          path: `/rooms/${room}/ai/${agentId}`,
+        };
+      case "ai_stop":
+        return { method: "POST", path: `/rooms/${room}/ai/stop` };
+      case "user_summary":
+        return { method: "GET", path: `/users/summary/${username}` };
+      default:
+        throw new Error(`No HTTP fallback route for channel message: ${message.type}`);
+    }
+  }
+}
+
+function enc(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  return encodeURIComponent(String(value));
+}
+
+function pick(
+  source: ChannelMessage,
+  keys: readonly string[],
+): Record<string, unknown> {
+  return keys.reduce<Record<string, unknown>>((acc, key) => {
+    const value = source[key];
+    if (value !== undefined) {
+      acc[key] = value;
+    }
+    return acc;
+  }, {});
+}
+
diff --git a/src/socket/index.ts b/src/socket/index.ts
new file mode 100644
index 0000000..fd3eabe
--- /dev/null
+++ b/src/socket/index.ts
@@ -0,0 +1,103 @@
+export { ChannelHttpFallback } from "./fallback";
+export { ChannelSocketClient, channelSocket } from "./manager";
+export { channelSocketStore, useChannelSocketState } from "./state";
+export { DedupManager } from "./dedup";
+export { ReconnectManager } from "./reconnect";
+export { RoomSubscriptionManager } from "./subscription";
+export type {
+  ChannelConnectionStatus,
+  ChannelErrorPayload,
+  ChannelEventHandler,
+  ChannelMessage,
+  ChannelOutEvent,
+  ChannelRequestOptions,
+  ChannelResponse,
+  ChannelSocketOptions,
+  ChannelSocketState,
+  ChannelTransport,
+  WsTokenRequest,
+  WsTokenResponse,
+} from "./types";
+export type {
+  AgentInfo,
+  AiAgentJoinedService,
+  AiAgentLeftService,
+  AiAgentStatusChangedService,
+  AttachmentUploadedService,
+  BannedService,
+  CategoryCreatedService,
+  CategoryDeletedService,
+  CategoryUpdatedService,
+  ConversationMutedService,
+  ConversationPinnedService,
+  ConversationSummary,
+  ConversationUnmutedService,
+  ConversationUnpinnedService,
+  ConversationUnreadUpdatedService,
+  CustomStatusUpdatedService,
+  DmClosedService,
+  DmCreatedService,
+  DmReopenedService,
+  DraftClearedService,
+  DraftSavedService,
+  InviteAcceptedService,
+  InviteCreatedService,
+  MessageEditedService,
+  MessageForwardedService,
+  MessageListService,
+  MessageNewService,
+  MessageReadBatchService,
+  MessageReaderEntry,
+  MessageReadersService,
+  MessageReadService,
+  MessageRevokedService,
+  MessageStarredService,
+  MessageStreamChunkService,
+  MessageStreamDoneService,
+  MessageStreamStartService,
+  MessageUnstarredService,
+  MemberJoinedService,
+  MemberRemovedService,
+  NotifyCreatedService,
+  NotifyReadService,
+  PinAddedService,
+  PinRemovedService,
+  PresenceChangedService,
+  ReactionAddedService,
+  ReactionBatchUpdatedService,
+  ReactionGroup,
+  ReactionRemovedService,
+  ReadReceiptService,
+  RoomAiEntry,
+  RoomAiListService,
+  RoomCreatedService,
+  RoomDeletedService,
+  RoomInfo,
+  RoomMovedService,
+  RoomRenamedService,
+  RoomSettingsUpdatedService,
+  RoomTopicUpdatedService,
+  SearchResultService,
+  SearchMessageHitService,
+  StarredMessageEntry,
+  TypingStartService,
+  TypingStopService,
+  ThreadArchivedService,
+  ThreadCreatedService,
+  ThreadResolvedService,
+  ThreadUpdatedService,
+  UnbannedService,
+  UserPresenceStatus,
+  UserInfo,
+  VoiceChannelJoinedService,
+  VoiceChannelLeftService,
+  WorkspaceInfo,
+  WorkspaceRoomCreatedService,
+  WorkspaceRoomDeletedService,
+  WsError,
+  WsOutEvent,
+} from "./schema";
+// IndexedDB message cache
+export { db } from "@/lib/db";
+export { MessageRepository } from "@/lib/db/repository";
+export type { CachedMessage, RoomSyncMeta } from "@/lib/db";
diff --git a/src/socket/manager.ts b/src/socket/manager.ts
new file mode 100644
index 0000000..5aedcf9
--- /dev/null
+++ b/src/socket/manager.ts
@@ -0,0 +1,677 @@
+import { io, type Socket } from "socket.io-client";
+
+import { api } from "@/client";
+
+import { ChannelHttpFallback } from "./fallback";
+import { channelSocketStore } from "./state";
+import { DedupManager } from "./dedup";
+import { ReconnectManager } from "./reconnect";
+import { RoomSubscriptionManager } from "./subscription";
+import type {
+  ChannelEventHandler,
+  ChannelMessage,
+  ChannelOutEvent,
+  ChannelRequestOptions,
+  ChannelSocketOptions,
+  ChannelTransport,
+  WsTokenRequest,
+  WsTokenResponse,
+} from "./types";
+
+type PendingRequest<T = unknown> = {
+  id: string;
+  message: ChannelMessage;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+  timeout: ReturnType<typeof setTimeout>;
+  fallback: boolean;
+};
+
+const defaultOptions = {
+  namespace: "/channel",
+  path: "/api/v1/ws/socket.io",
+  restBasePath: "/api/v1/ws",
+  eventName: "channel.message",
+  windowSize: 16,
+  timeoutMs: 30_000,
+  fallback: true,
+  autoConnect: true,
+} satisfies Required<Omit<ChannelSocketOptions, "url">>;
+
+export class ChannelSocketClient {
+  private readonly options: Required<ChannelSocketOptions>;
+  private readonly fallback: ChannelHttpFallback;
+  private readonly handlers = new Set<ChannelEventHandler>();
+  private readonly queue: PendingRequest[] = [];
+  private readonly inFlight = new Map<string, PendingRequest>();
+  private socket: Socket | null = null;
+  private accessToken: string | null = null;
+  private isConnecting = false;
+  private readonly deviceId: string;
+  /** Offline message queue — buffers user-action messages during disconnect. */
+  private readonly offlineQueue: ChannelMessage[] = [];
+  private readonly OFFLINE_QUEUE_MAX = 100;
+  /** Dedup prevents processing the same event twice. */
+  private readonly dedup = new DedupManager();
+  /** Exponential-backoff reconnect manager. */
+  private readonly reconnect = new ReconnectManager();
+  /** Room subscription tracker — auto-resubscribes on reconnect. */
+  private readonly subscriptions = new RoomSubscriptionManager();
+
+  constructor(options: ChannelSocketOptions = {}) {
+    this.options = { url: "", ...defaultOptions, ...options };
+    this.fallback = new ChannelHttpFallback(undefined, this.options.restBasePath);
+    this.deviceId = crypto.randomUUID();
+    this.reconnect.setCallback(() => this.initConnection());
+    this.subscriptions.setCallbacks(
+      () => {}, // subscribe — no-op, handled by ChannelSocketClient.subscribe
+      () => {}, // unsubscribe — no-op
+    );
+    // Defer autoConnect to first usage — ChannelSocketProvider calls connect()
+    // when the user is authenticated. Module-level instantiation should not
+    // connect before auth state is ready.
+  }
+
+  connect(): void {
+    if (this.isConnecting) {
+      return;
+    }
+    if (this.socket?.connected || this.socket?.active) {
+      return;
+    }
+
+    channelSocketStore.setState({
+      status: "connecting",
+      connected: false,
+      lastError: null,
+    });
+
+    this.isConnecting = true;
+    this.initConnection().finally(() => {
+      this.isConnecting = false;
+    });
+  }
+
+  /** Fetch token, create socket — for both initial connect and reconnect. */
+  private async initConnection(): Promise<void> {
+    channelSocketStore.setState({
+      status: this.socket ? 'reconnecting' : 'connecting',
+      connected: false,
+      transport: 'unknown',
+    });
+
+    // Fetch WS access token before connecting.
+    try {
+      await this.fetchAccessToken();
+    } catch {
+      // Token unavailable, continue with session cookie only.
+    }
+
+    // Clean up old socket before creating new one — prevents WebSocket leak.
+    if (this.socket) {
+      this.socket.off();
+      this.socket.disconnect();
+    }
+
+    const authData = this.accessToken
+      ? { access_token: this.accessToken }
+      : undefined;
+
+    const endpoint = `${this.options.url}${this.options.namespace}`;
+    this.socket = io(endpoint, {
+      path: this.options.path,
+      transports: ["websocket", "polling"],
+      withCredentials: true,
+      autoConnect: true,
+      reconnection: false,
+      auth: authData,
+    });
+
+    this.bindSocketEvents();
+  }
+
+  private async fetchAccessToken(): Promise<string> {
+    const body: WsTokenRequest = {
+      device_id: this.deviceId,
+      client_id: "web",
+    };
+    const res = await api.post<WsTokenResponse>(
+      `${this.options.restBasePath}/token`,
+      body,
+    );
+    this.accessToken = res.data.access_token;
+      Date.now() + res.data.expires_in_secs * 1000;
+    return this.accessToken;
+  }
+
+  private bindSocketEvents(): void {
+    if (!this.socket) {
+      return;
+    }
+
+    this.socket.on("connect", () => {
+      this.isConnecting = false;
+      this.reconnect.succeed();
+      channelSocketStore.setState({
+        status: "connected",
+        connected: true,
+        transport: this.currentTransport(),
+        lastError: null,
+      });
+      this.flushOfflineQueue();
+      // Re-subscribe all tracked rooms on reconnect
+      for (const roomId of this.subscriptions.getSubscribedRooms()) {
+        this.send({ type: "subscribe", room: roomId });
+      }
+      this.drain();
+    });
+    this.socket.io.on("reconnect_attempt", () => {
+      // Socket.IO internal reconnect is disabled; ReconnectManager handles it.
+      // Update state only — no fail() call here.
+      channelSocketStore.setState({
+        status: "reconnecting",
+        connected: false,
+        transport: "unknown",
+      });
+    });
+    this.socket.on("disconnect", (reason) => {
+      channelSocketStore.setState({
+        status: "disconnected",
+        connected: false,
+        transport: "unknown",
+        lastError: reason,
+      });
+      this.rejectAllPending(
+        new Error(`Socket disconnected: ${reason}`),
+      );
+      this.flushToHttp();
+      // Buffer user-action messages for reconnect
+      this.enqueueForReconnect();
+      // Trigger ReconnectManager to schedule reconnection
+      if (this.options.autoConnect) {
+        this.reconnect.fail();
+      }
+    });
+    this.socket.on("connect_error", (error) => {
+      channelSocketStore.setState({
+        status: "error",
+        connected: false,
+        transport: "unknown",
+        lastError: error.message,
+      });
+      this.rejectAllPending(
+        new Error(`Socket connect error: ${error.message}`),
+      );
+      this.flushToHttp();
+      // Trigger ReconnectManager to schedule reconnection
+      if (this.options.autoConnect) {
+        this.reconnect.fail();
+      }
+    });
+    this.socket.on(this.options.eventName, (raw: unknown) => {
+      this.handleEvent(raw);
+    });
+    // Backend broadcasts room-level events (typing, reactions, new messages,
+    // member join/leave, etc.) on "room.message".  We convert them into the
+    // same WsOutEvent-compatible shapes that handleEvent expects.
+    this.socket.on("room.message", (raw: unknown) => {
+      this.handleRoomEvent(raw);
+    });
+  }
+
+  private rejectAllPending(reason: Error): void {
+    for (const [id, pending] of this.inFlight) {
+      clearTimeout(pending.timeout);
+      pending.reject(reason);
+      this.inFlight.delete(id);
+    }
+    for (const pending of this.queue) {
+      clearTimeout(pending.timeout);
+      pending.reject(reason);
+    }
+    this.queue.length = 0;
+    this.syncWindowState();
+  }
+
+  disconnect(): void {
+    this.reconnect.stop();
+    this.socket?.disconnect();
+    this.socket?.removeAllListeners();
+    this.socket = null;
+    this.isConnecting = false;
+    this.accessToken = null;
+    this.offlineQueue.length = 0;
+    this.rejectAllPending(new Error("Channel socket disconnected"));
+    channelSocketStore.setState({
+      status: "disconnected",
+      connected: false,
+      transport: "unknown",
+    });
+  }
+
+  on(handler: ChannelEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+
+  request<T = unknown>(
+    message: ChannelMessage,
+    options: ChannelRequestOptions = {},
+  ): Promise<T> {
+    if (!this.isConnected() && (options.fallback ?? this.options.fallback)) {
+      channelSocketStore.setState({ transport: "http" });
+      return this.fallback.request<T>(message);
+    }
+
+    if (!this.socket) {
+      this.connect();
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      const id = crypto.randomUUID();
+      const timeoutMs = options.timeoutMs ?? this.options.timeoutMs;
+      const pending: PendingRequest<T> = {
+        id,
+        message: { ...message, _request_id: id },
+        resolve,
+        reject,
+        fallback: options.fallback ?? this.options.fallback,
+        timeout: setTimeout(() => {
+          this.inFlight.delete(id);
+          this.removeQueued(id);
+          this.syncWindowState();
+          reject(new Error(`Channel request timed out: ${message.type}`));
+          this.drain();
+        }, timeoutMs),
+      };
+      this.queue.push(pending as PendingRequest);
+      this.syncWindowState();
+      this.drain();
+    });
+  }
+
+  send(message: ChannelMessage, options?: ChannelRequestOptions): Promise<void> {
+    // When disconnected, buffer user-action messages for re-delivery on reconnect.
+    // Do NOT also call request() — that would send via HTTP fallback and cause duplicates.
+    if (!this.isConnected()) {
+      if (this.isBuffereable(message.type)) {
+        this.offlineQueue.push(message);
+        if (this.offlineQueue.length > this.OFFLINE_QUEUE_MAX) {
+          this.offlineQueue.shift();
+        }
+      }
+      // For buffered messages, resolve immediately — they'll be sent on reconnect.
+      // For non-buffered, still try HTTP fallback.
+      if (this.isBuffereable(message.type)) {
+        if (!(options?.fallback ?? this.options.fallback)) {
+          return Promise.resolve();
+        }
+      }
+    }
+    return this.request(message, options).then(() => undefined);
+  }
+
+  private isBuffereable(type: string): boolean {
+    const bufs = new Set([
+      "message_create", "message_update", "message_revoke",
+      "reaction_add", "reaction_remove",
+      "read_receipt", "draft_save", "draft_clear",
+    ]);
+    return bufs.has(type);
+  }
+
+  private flushOfflineQueue(): void {
+    const batch = this.offlineQueue.splice(0);
+    for (const msg of batch) {
+      if (!this.socket?.connected) break;
+      this.socket.emit(this.options.eventName, msg);
+    }
+  }
+
+  private enqueueForReconnect(): void {
+    // In-flight requests that are buffereable get re-queued
+    for (const [, pending] of this.inFlight) {
+      if (this.isBuffereable(pending.message.type)) {
+        this.offlineQueue.push(pending.message);
+      }
+    }
+  }
+
+  subscribe(room: string): Promise<void> {
+    if (this.subscriptions.isSubscribed(room)) return Promise.resolve();
+    // Track locally first, then send WS message
+    this.subscriptions.subscribe(room);
+    return this.send({ type: "subscribe", room });
+  }
+
+  unsubscribe(room: string): Promise<void> {
+    if (!this.subscriptions.isSubscribed(room)) return Promise.resolve();
+    this.subscriptions.unsubscribe(room);
+    return this.send({ type: "unsubscribe", room });
+  }
+
+  private drain(): void {
+    if (!this.socket?.connected) {
+      return;
+    }
+
+    while (
+      this.queue.length > 0 &&
+      this.inFlight.size < this.options.windowSize
+    ) {
+      const pending = this.queue.shift();
+      if (!pending) {
+        continue;
+      }
+      this.inFlight.set(pending.id, pending);
+      this.socket.emit(this.options.eventName, pending.message);
+    }
+    this.syncWindowState();
+  }
+
+  private handleEvent(raw: unknown): void {
+    const event = parseEvent(raw);
+    if (!event) {
+      return;
+    }
+
+    if (event.type === "response") {
+      const resp = event as Extract<typeof event, { type: "response" }>;
+      this.resolveResponse(resp);
+      return;
+    }
+
+    // Client-side dedup: skip already-seen message events.
+    if (this.shouldDedup(event)) return;
+
+    for (const handler of this.handlers) {
+      handler(event);
+    }
+  }
+
+  /** Returns true if the event was already seen (duplicate). */
+  private shouldDedup(event: ChannelOutEvent): boolean {
+    if (event.type === "message_new") {
+      const data = event.data as { id?: string };
+      const roomId = (event as { room?: { id?: string } }).room?.id ?? "";
+      if (data?.id) return this.dedup.checkAndMark(data.id, roomId);
+    }
+    return false;
+  }
+
+  /**
+   * Convert a backend ChannelEvent (received on \"room.message\") into the
+   * WsOutEvent-compatible shape expected by registered handlers.
+   */
+  private handleRoomEvent(raw: unknown): void {
+    const event = roomEventToOutEvent(raw);
+    if (!event) {
+      return;
+    }
+    // Client-side dedup on room events too.
+    if (this.shouldDedup(event)) return;
+    for (const handler of this.handlers) {
+      handler(event);
+    }
+  }
+
+  private resolveResponse(event: { request_id: string; data: unknown }): void {
+    const requestId = event.request_id;
+    if (typeof requestId !== "string") {
+      return;
+    }
+
+    const pending = this.inFlight.get(requestId);
+    if (!pending) {
+      return;
+    }
+
+    this.inFlight.delete(requestId);
+    clearTimeout(pending.timeout);
+    this.syncWindowState();
+
+    if (isErrorPayload(event.data)) {
+      pending.reject(toError(event.data));
+    } else {
+      pending.resolve(event.data);
+    }
+    this.drain();
+  }
+
+  private flushToHttp(): void {
+    if (!this.options.fallback) {
+      return;
+    }
+
+    const pending = [...this.inFlight.values(), ...this.queue].filter(
+      (item) => item.fallback,
+    );
+    const nonFallback = [...this.inFlight.values(), ...this.queue].filter(
+      (item) => !item.fallback,
+    );
+    this.inFlight.clear();
+    this.queue.length = 0;
+    this.syncWindowState();
+
+    for (const item of nonFallback) {
+      clearTimeout(item.timeout);
+      item.reject(new Error("Connection lost, no HTTP fallback available"));
+    }
+
+    for (const item of pending) {
+      clearTimeout(item.timeout);
+      this.fallback
+        .request(item.message)
+        .then(item.resolve)
+        .catch(item.reject);
+    }
+  }
+
+  private isConnected(): boolean {
+    return this.socket?.connected === true;
+  }
+
+  private currentTransport(): ChannelTransport {
+    const name = this.socket?.io.engine?.transport?.name;
+    if (name === "websocket" || name === "polling") {
+      return name;
+    }
+    return "unknown";
+  }
+
+  private removeQueued(id: string): void {
+    const index = this.queue.findIndex((item) => item.id === id);
+    if (index >= 0) {
+      this.queue.splice(index, 1);
+    }
+  }
+
+  private syncWindowState(): void {
+    channelSocketStore.setState({
+      inFlight: this.inFlight.size,
+      queued: this.queue.length,
+    });
+  }
+}
+
+export const channelSocket = new ChannelSocketClient();
+
+function parseEvent(raw: unknown): ChannelOutEvent | null {
+  if (typeof raw === "string") {
+    try {
+      return parseEvent(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  }
+
+  if (raw && typeof raw === "object" && "type" in raw && typeof (raw as Record<string, unknown>).type === "string") {
+    return raw as ChannelOutEvent;
+  }
+
+  return null;
+}
+
+function isErrorPayload(value: unknown): value is { error: string; message?: string } {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "error" in value &&
+    typeof (value as { error?: unknown }).error === "string"
+  );
+}
+
+function toError(payload: { error: string; message?: string }): Error {
+  const error = new Error(payload.message ?? payload.error);
+  error.name = payload.error;
+  return error;
+}
+
+// --- Backend ChannelEvent → Frontend WsOutEvent converter ---
+// The backend broadcasts room-level events on "room.message" as
+// ChannelEvent { room, seq, event_type, message, payload }.
+// We convert them into the WsOutEvent shapes expected by the frontend.
+
+interface RawChannelEvent {
+  room: string;
+  seq: number | null;
+  event_type: string;
+  message: unknown;
+  payload: unknown;
+  sender_user?: { id: string; username: string; display_name: string; avatar_url: string };
+}
+
+const EVENT_TYPE_MAP: Record<string, string> = {
+  "message.created": "message_new",
+  "message.edited": "message_edited",
+  "message.revoked": "message_revoked",
+  "message.stream_start": "message_stream_start",
+  "message.stream_chunk": "message_stream_chunk",
+  "message.stream_done": "message_stream_done",
+  "message.read_batch": "message_read_batch",
+  "message.read": "message_read",
+  "message.forwarded": "message_forwarded",
+  "typing.start": "typing_start",
+  "typing.stop": "typing_stop",
+  "reaction.added": "reaction_added",
+  "reaction.removed": "reaction_removed",
+  "member.read_receipt": "read_receipt",
+  "member.joined": "member_joined",
+  "member.removed": "member_removed",
+  "member.dnd_updated": "dnd_updated",
+  "thread.created": "thread_created",
+  "thread.updated": "thread_updated",
+  "thread.resolved": "thread_resolved",
+  "thread.archived": "thread_archived",
+  "pin.added": "pin_added",
+  "pin.removed": "pin_removed",
+  "room.created": "room_created",
+  "room.deleted": "room_deleted",
+  "room.renamed": "room_renamed",
+  "room.topic_updated": "room_topic_updated",
+  "room.settings_updated": "room_settings_updated",
+  "room.moved": "room_moved",
+  "category.created": "category_created",
+  "category.updated": "category_updated",
+  "category.deleted": "category_deleted",
+  "voice.channel_joined": "voice_channel_joined",
+  "voice.channel_left": "voice_channel_left",
+  "voice.mute_updated": "voice_mute_updated",
+  "voice.deaf_updated": "voice_deaf_updated",
+  "voice.screen_share": "screen_share_started",
+  "presence.changed": "presence_changed",
+  "custom_status.updated": "custom_status_updated",
+  "draft.saved": "draft_saved",
+  "draft.cleared": "draft_cleared",
+  "ai.agent_joined": "ai_agent_joined",
+  "ai.agent_left": "ai_agent_left",
+  "ai.agent_status_changed": "ai_agent_status_changed",
+  "ai.stop": "ai_stop",
+  "invite.created": "invite_created",
+  "invite.accepted": "invite_accepted",
+  "notify.created": "notify_created",
+  "notify.read": "notify_read",
+  "attachment.uploaded": "attachment_uploaded",
+  "attachment.deleted": "attachment_deleted",
+  "ban.created": "user_banned",
+  "ban.removed": "user_unbanned",
+};
+
+/** Convert a RoomMessageModel (from backend ChannelEvent.message) into
+ *  MessageNewService shape that the frontend expects.
+ *  Uses sender_user from the ChannelEvent when available. */
+function messageModelToService(
+  m: Record<string, unknown>,
+  roomId: string,
+  senderUser?: { id: string; username: string; display_name: string; avatar_url: string },
+): Record<string, unknown> {
+  return {
+    id: m.id,
+    seq: m.seq,
+    room: { id: m.room ?? roomId, name: "" },
+    sender_type: "user",
+    sender: senderUser ?? {
+      id: m.author ?? "",
+      username: "",
+      display_name: "Unknown",
+      avatar_url: "",
+    },
+    thread: m.thread ?? null,
+    in_reply_to: m.parent ?? m.in_reply_to ?? null,
+    content: m.content ?? "",
+    content_type: m.content_type ?? "text",
+    pinned: m.pinned ?? false,
+    system_type: m.system_type ?? null,
+    metadata: m.metadata ?? {},
+    thinking_content: null,
+    thinking_is_chunked: null,
+    send_at: m.created_at ?? new Date().toISOString(),
+    reactions: [],
+  };
+}
+
+function roomEventToOutEvent(raw: unknown): ChannelOutEvent | null {
+  const ev = normalizePayload(raw);
+  if (!ev) return null;
+
+  // message.created: the backend sends RoomMessageModel in ev.message.
+  // We need to rewrite author → sender for the frontend MessageNewService.
+  if (ev.event_type === "message.created" && ev.message) {
+    return {
+      type: "message_new",
+      room: { id: ev.room, name: "" },
+      data: messageModelToService(
+        ev.message as Record<string, unknown>,
+        ev.room,
+        ev.sender_user,
+      ),
+    } as ChannelOutEvent;
+  }
+
+  const outType = EVENT_TYPE_MAP[ev.event_type];
+  if (!outType) return null;
+
+  // All other events carry structured data in ev.payload.
+  return {
+    type: outType,
+    room: { id: ev.room, name: "" },
+    data: ev.payload,
+  } as ChannelOutEvent;
+}
+
+function normalizePayload(raw: unknown): RawChannelEvent | null {
+  if (typeof raw === "string") {
+    try { return normalizePayload(JSON.parse(raw)); } catch { return null; }
+  }
+  if (
+    raw &&
+    typeof raw === "object" &&
+    "event_type" in raw &&
+    typeof (raw as Record<string, unknown>).event_type === "string"
+  ) {
+    return raw as RawChannelEvent;
+  }
+  return null;
+}
diff --git a/src/socket/reconnect.ts b/src/socket/reconnect.ts
new file mode 100644
index 0000000..19228c7
--- /dev/null
+++ b/src/socket/reconnect.ts
@@ -0,0 +1,80 @@
+/**
+ * Exponential-backoff reconnect manager.
+ *
+ * Starts at 1s delay, doubles each failure (max 30s).
+ * On success or manual reset, delay resets to 1s.
+ */
+export class ReconnectManager {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private retryCount = 0;
+  private readonly maxRetries: number;
+  private readonly baseDelayMs: number;
+  private readonly maxDelayMs: number;
+  private callback: (() => void) | null = null;
+
+  constructor(maxRetries = 20, baseDelayMs = 1000, maxDelayMs = 30_000) {
+    this.maxRetries = maxRetries;
+    this.baseDelayMs = baseDelayMs;
+    this.maxDelayMs = maxDelayMs;
+  }
+
+  setCallback(cb: () => void): void {
+    this.callback = cb;
+  }
+
+  get isReconnecting(): boolean {
+    return this.timer !== null;
+  }
+
+  get state(): { isReconnecting: boolean; retryCount: number } {
+    return { isReconnecting: this.isReconnecting, retryCount: this.retryCount };
+  }
+
+  /** Start reconnection loop. Resets counter if starting fresh. */
+  start(): void {
+    this.stop();
+    this.schedule();
+  }
+
+  /** Called when connection succeeds — resets backoff. */
+  succeed(): void {
+    this.stop();
+    this.retryCount = 0;
+  }
+
+  /** Called when a reconnection attempt fails — increments backoff. */
+  fail(): void {
+    if (this.retryCount >= this.maxRetries) {
+      this.stop();
+      return;
+    }
+    // Stop existing timer before scheduling new one to prevent duplicate timers.
+    this.stop();
+    this.schedule();
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Reset backoff and start immediately (e.g., tab becomes visible). */
+  resetAndStart(): void {
+    this.stop();
+    this.retryCount = 0;
+    if (this.callback) this.callback();
+  }
+
+  private schedule(): void {
+    const delay = Math.min(
+      this.baseDelayMs * Math.pow(2, this.retryCount),
+      this.maxDelayMs,
+    );
+    this.timer = setTimeout(() => {
+      this.retryCount++;
+      if (this.callback) this.callback();
+    }, delay);
+  }
+}
diff --git a/src/socket/schema.ts b/src/socket/schema.ts
new file mode 100644
index 0000000..a5f0b98
--- /dev/null
+++ b/src/socket/schema.ts
@@ -0,0 +1,691 @@
+// --- Enriched types (server→client) ---
+export type UserInfo = {
+  id: string;
+  username: string;
+  display_name: string;
+  avatar_url: string;
+};
+
+export type RoomInfo = {
+  id: string;
+  name: string;
+};
+
+export type WorkspaceInfo = {
+  id: string;
+  name: string;
+  avatar_url: string;
+};
+
+export type AgentInfo = {
+  id: string;
+  name: string;
+  agent_type: string;
+  model_name: string | null;
+};
+
+// --- Enums ---
+export type UserPresenceStatus = "online" | "idle" | "dnd" | "offline";
+
+// --- Reactions ---
+export type ReactionGroup = {
+  emoji: string;
+  count: number;
+  reacted_by_me: boolean;
+  users: UserInfo[];
+};
+
+// --- Message Service structs ---
+export type MessageNewService = {
+  id: string;
+  seq: number;
+  room: RoomInfo;
+  sender_type: string;
+  sender: UserInfo;
+  thread: string | null;
+  in_reply_to: string | null;
+  content: string;
+  content_type: string;
+  pinned?: boolean;
+  system_type: string | null;
+  metadata: Record<string, unknown>;
+  thinking_content: string | null;
+  thinking_is_chunked: boolean | null;
+  send_at: string;
+  reactions: ReactionGroup[];
+};
+
+export type MessageEditedService = {
+  id: string;
+  seq: number;
+  room: RoomInfo;
+  sender: UserInfo;
+  content: string;
+  edited_at: string;
+};
+
+export type MessageRevokedService = {
+  id: string;
+  seq: number;
+  room: RoomInfo;
+  revoked_by: UserInfo;
+  revoked_at: string;
+};
+
+export type MessageStreamStartService = {
+  message_id: string;
+  room: RoomInfo;
+  sse_url: string | null;
+  display_name: string | null;
+};
+
+export type MessageStreamChunkService = {
+  message_id: string;
+  room: RoomInfo;
+  seq: number;
+  content: string;
+  chunk_type: string;
+  display_name: string | null;
+};
+
+export type MessageStreamDoneService = {
+  message_id: string;
+  room: RoomInfo;
+  content: string;
+  thinking_content: string | null;
+  display_name: string | null;
+  error: string | null;
+};
+
+export type MessageListService = {
+  room: RoomInfo;
+  messages: MessageNewService[];
+  total: number;
+};
+
+// --- Member Service structs ---
+export type MemberJoinedService = {
+  room: RoomInfo;
+  user: UserInfo;
+  project_role: string | null;
+  joined_at: string;
+};
+
+export type MemberRemovedService = {
+  room: RoomInfo;
+  user: UserInfo;
+  removed_by: UserInfo;
+  removed_at: string;
+};
+
+export type ReadReceiptService = {
+  room: RoomInfo;
+  user: UserInfo;
+  last_read_seq: number;
+  updated_at: string;
+};
+
+export type TypingStartService = {
+  room: RoomInfo;
+  user: UserInfo;
+  sender_type: string;
+  started_at: string;
+};
+
+export type TypingStopService = {
+  room: RoomInfo;
+  user: UserInfo;
+  sender_type: string;
+  stopped_at: string;
+};
+
+// --- Reaction Service structs ---
+export type ReactionAddedService = {
+  id: string;
+  room: RoomInfo;
+  message: string;
+  user: UserInfo;
+  emoji: string;
+  created_at: string;
+};
+
+export type ReactionRemovedService = {
+  id: string;
+  room: RoomInfo;
+  message: string;
+  user: UserInfo;
+  emoji: string;
+  removed_at: string;
+};
+
+export type ReactionBatchUpdatedService = {
+  room: RoomInfo;
+  message: string;
+  reactions: ReactionGroup[];
+};
+
+// --- Thread Service structs ---
+export type ThreadCreatedService = {
+  id: string;
+  room: RoomInfo;
+  parent: number;
+  created_by: UserInfo;
+  participants: unknown;
+  created_at: string;
+};
+
+export type ThreadUpdatedService = {
+  id: string;
+  room: RoomInfo;
+  last_message_at: string | null;
+  last_message_preview: string | null;
+  updated_at: string;
+};
+
+export type ThreadResolvedService = {
+  id: string;
+  room: RoomInfo;
+  resolved_by: UserInfo;
+  resolved_at: string;
+};
+
+export type ThreadArchivedService = {
+  id: string;
+  room: RoomInfo;
+  archived_by: UserInfo;
+  archived_at: string;
+};
+
+// --- Pin Service structs ---
+export type PinAddedService = {
+  room: RoomInfo;
+  message: string;
+  pinned_by: UserInfo;
+  pinned_at: string;
+};
+
+export type PinRemovedService = {
+  room: RoomInfo;
+  message: string;
+  removed_by: UserInfo;
+  removed_at: string;
+};
+
+// --- Draft Service structs ---
+export type DraftSavedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  content: string;
+  saved_at: string;
+};
+
+export type DraftClearedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  cleared_at: string;
+};
+
+// --- Room Service structs ---
+export type RoomCreatedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo;
+  public: boolean;
+  category: string | null;
+  created_by: UserInfo;
+  created_at: string;
+};
+
+export type RoomDeletedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo;
+  deleted_by: UserInfo;
+  deleted_at: string;
+};
+
+export type RoomRenamedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo;
+  old_name: string;
+  new_name: string;
+  renamed_by: UserInfo;
+  renamed_at: string;
+};
+
+export type RoomMovedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo;
+  old_category: string | null;
+  new_category: string | null;
+  moved_by: UserInfo;
+  moved_at: string;
+};
+
+export type RoomTopicUpdatedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo;
+  old_topic: string | null;
+  new_topic: string | null;
+  updated_by: UserInfo;
+  updated_at: string;
+};
+
+export type RoomSettingsUpdatedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo;
+  slowmode_seconds: number | null;
+  nsfw: boolean;
+  default_auto_archive_duration: number | null;
+  updated_by: UserInfo;
+  updated_at: string;
+};
+
+// --- Workspace Service structs ---
+export type WorkspaceRoomCreatedService = {
+  workspace: WorkspaceInfo;
+  room: RoomInfo;
+  public: boolean;
+  category: string | null;
+  created_by: UserInfo;
+  created_at: string;
+};
+
+export type WorkspaceRoomDeletedService = {
+  workspace: WorkspaceInfo;
+  room: RoomInfo;
+  deleted_by: UserInfo;
+  deleted_at: string;
+};
+
+// --- Category Service structs ---
+export type CategoryCreatedService = {
+  id: string;
+  workspace: WorkspaceInfo;
+  name: string;
+  position: number;
+  created_by: UserInfo;
+  created_at: string;
+};
+
+export type CategoryUpdatedService = {
+  id: string;
+  workspace: WorkspaceInfo;
+  name: string | null;
+  position: number | null;
+  updated_by: UserInfo;
+  updated_at: string;
+};
+
+export type CategoryDeletedService = {
+  id: string;
+  workspace: WorkspaceInfo;
+  deleted_by: UserInfo;
+  deleted_at: string;
+};
+
+// --- Notify Service structs ---
+export type NotifyCreatedService = {
+  id: string;
+  room: RoomInfo | null;
+  workspace: WorkspaceInfo | null;
+  user: UserInfo;
+  notification_type: string;
+  title: string;
+  content: string | null;
+  related_message_id: string | null;
+  related_user: UserInfo | null;
+  metadata: unknown;
+  created_at: string;
+  deep_link_url: string | null;
+};
+
+export type NotifyReadService = {
+  id: string;
+  user: UserInfo;
+  read_at: string;
+};
+
+// --- Presence Service structs ---
+export type PresenceChangedService = {
+  user: UserInfo;
+  workspace: WorkspaceInfo | null;
+  status: UserPresenceStatus;
+  last_seen_at: string | null;
+};
+
+export type CustomStatusUpdatedService = {
+  user: UserInfo;
+  emoji: string | null;
+  text: string | null;
+  expires_at: string | null;
+};
+
+// --- Invite Service structs ---
+export type InviteCreatedService = {
+  id: string;
+  workspace: WorkspaceInfo;
+  room: RoomInfo | null;
+  inviter: UserInfo;
+  invitee: UserInfo | null;
+  code: string;
+  max_uses: number | null;
+  expires_at: string | null;
+  created_at: string;
+};
+
+export type InviteAcceptedService = {
+  id: string;
+  workspace: WorkspaceInfo;
+  room: RoomInfo | null;
+  user: UserInfo;
+  accepted_at: string;
+};
+
+// --- Ban Service structs ---
+export type BannedService = {
+  workspace: WorkspaceInfo;
+  user: UserInfo;
+  banned_by: UserInfo;
+  reason: string | null;
+  expires_at: string | null;
+  banned_at: string;
+};
+
+export type UnbannedService = {
+  workspace: WorkspaceInfo;
+  user: UserInfo;
+  unbanned_by: UserInfo;
+  unbanned_at: string;
+};
+
+// --- Voice Service structs ---
+export type VoiceChannelJoinedService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo | null;
+  user: UserInfo;
+  muted: boolean;
+  deafened: boolean;
+  video: boolean;
+  joined_at: string;
+};
+
+export type VoiceChannelLeftService = {
+  room: RoomInfo;
+  workspace: WorkspaceInfo | null;
+  user: UserInfo;
+  left_at: string;
+};
+
+// --- AI Service structs ---
+export type AiAgentJoinedService = {
+  room: RoomInfo;
+  agent: AgentInfo;
+  joined_at: string;
+};
+
+export type AiAgentLeftService = {
+  room: RoomInfo;
+  agent: AgentInfo;
+  left_at: string;
+};
+
+export type RoomAiEntry = {
+  agent_session: string;
+  name: string;
+  agent_kind: string;
+  model_version: string | null;
+  enabled: boolean;
+  auto_reply: boolean;
+};
+
+export type RoomAiListService = {
+  room: RoomInfo;
+  agents: RoomAiEntry[];
+};
+
+export type AiAgentStatusChangedService = {
+  room: RoomInfo;
+  agent: AgentInfo;
+  old_status: string;
+  new_status: string;
+  changed_at: string;
+};
+
+// --- Search Service structs ---
+export type SearchMessageHitService = MessageNewService & {
+  highlighted_content: string;
+};
+
+export type SearchResultService = {
+  q: string;
+  room: RoomInfo | null;
+  messages: SearchMessageHitService[];
+  total: number;
+  took_ms: number;
+};
+
+// --- Attachment Service structs ---
+export type AttachmentUploadedService = {
+  id: string;
+  room: RoomInfo;
+  message: string;
+  filename: string;
+  content_type: string | null;
+  size: number;
+  url: string | null;
+  uploaded_by: UserInfo;
+  uploaded_at: string;
+};
+
+// --- Conversation state (OpenIM Conversation model) ---
+export type ConversationPinnedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  pinned_at: string;
+};
+
+export type ConversationUnpinnedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  unpinned_at: string;
+};
+
+export type ConversationMutedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  muted_at: string;
+};
+
+export type ConversationUnmutedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  unmuted_at: string;
+};
+
+export type ConversationUnreadUpdatedService = {
+  user: UserInfo;
+  room: RoomInfo;
+  last_read_seq: number;
+  unread_count: number;
+  updated_at: string;
+};
+
+export type ConversationSummary = {
+  room: string;
+  room_name: string;
+  room_type: string;
+  is_pinned: boolean;
+  is_muted: boolean;
+  notify_level: string;
+  last_read_seq: number;
+  max_seq: number;
+  unread_count: number;
+  last_read_at: string | null;
+};
+
+// --- Direct messaging (OpenIM SingleChat + Rocket.Chat DM) ---
+export type DmCreatedService = {
+  room: RoomInfo;
+  initiator: UserInfo;
+  recipient: UserInfo;
+  created_at: string;
+};
+
+export type DmClosedService = {
+  room: RoomInfo;
+  closed_by: UserInfo;
+  closed_at: string;
+};
+
+export type DmReopenedService = {
+  room: RoomInfo;
+  reopened_by: UserInfo;
+  reopened_at: string;
+};
+
+// --- Per-message read tracking (OpenIM MarkMsgsAsRead) ---
+export type MessageReadService = {
+  room: RoomInfo;
+  message_id: string;
+  message_seq: number;
+  reader: UserInfo;
+  read_at: string;
+};
+
+export type MessageReadBatchService = {
+  room: RoomInfo;
+  message_ids: string[];
+  last_seq: number;
+  reader: UserInfo;
+  read_at: string;
+};
+
+export type MessageReaderEntry = {
+  user: UserInfo;
+  read_at: string;
+};
+
+export type MessageReadersService = {
+  message_id: string;
+  readers: MessageReaderEntry[];
+};
+
+// --- Message starring (Rocket.Chat starMessage) ---
+export type MessageStarredService = {
+  room: RoomInfo;
+  message_id: string;
+  message_seq: number;
+  starred_by: UserInfo;
+  starred_at: string;
+};
+
+export type MessageUnstarredService = {
+  room: RoomInfo;
+  message_id: string;
+  unstarred_by: UserInfo;
+  unstarred_at: string;
+};
+
+export type StarredMessageEntry = {
+  message_id: string;
+  room: RoomInfo;
+  seq: number;
+  content: string;
+  content_type: string;
+  sender: UserInfo;
+  starred_at: string;
+  sent_at: string;
+};
+
+// --- Message forwarding (OpenIM forward) ---
+export type MessageForwardedService = {
+  id: string;
+  seq: number;
+  room: RoomInfo;
+  sender: UserInfo;
+  content: string;
+  content_type: string;
+  source_room: RoomInfo;
+  source_message_id: string;
+  forwarded_at: string;
+};
+
+// --- WsOutEvent discriminated union ---
+export type WsError = {
+  type: "error";
+  code: number;
+  error: string;
+  message: string;
+};
+
+export type WsOutEvent =
+  | { type: "pong"; protocol_version: number }
+  | WsError
+  | { type: "csrf_token"; token: string }
+  | { type: "room_created"; room: RoomInfo; data: RoomCreatedService }
+  | { type: "room_deleted"; room: RoomInfo; data: RoomDeletedService }
+  | { type: "room_renamed"; room: RoomInfo; data: RoomRenamedService }
+  | { type: "room_topic_updated"; room: RoomInfo; data: RoomTopicUpdatedService }
+  | { type: "room_settings_updated"; room: RoomInfo; data: RoomSettingsUpdatedService }
+  | { type: "room_moved"; room: RoomInfo; data: RoomMovedService }
+  | { type: "message_new"; room: RoomInfo; data: MessageNewService }
+  | { type: "message_edited"; room: RoomInfo; data: MessageEditedService }
+  | { type: "message_revoked"; room: RoomInfo; data: MessageRevokedService }
+  | { type: "message_stream_start"; room: RoomInfo; data: MessageStreamStartService }
+  | { type: "message_stream_chunk"; room: RoomInfo; data: MessageStreamChunkService }
+  | { type: "message_stream_done"; room: RoomInfo; data: MessageStreamDoneService }
+  | { type: "message_list"; room: RoomInfo; data: MessageListService }
+  | { type: "member_joined"; room: RoomInfo; data: MemberJoinedService }
+  | { type: "member_removed"; room: RoomInfo; data: MemberRemovedService }
+  | { type: "read_receipt"; room: RoomInfo; data: ReadReceiptService }
+  | { type: "typing_start"; room: RoomInfo; data: TypingStartService }
+  | { type: "typing_stop"; room: RoomInfo; data: TypingStopService }
+  | { type: "reaction_added"; room: RoomInfo; data: ReactionAddedService }
+  | { type: "reaction_removed"; room: RoomInfo; data: ReactionRemovedService }
+  | { type: "reaction_batch_updated"; room: RoomInfo; data: ReactionBatchUpdatedService }
+  | { type: "thread_created"; room: RoomInfo; data: ThreadCreatedService }
+  | { type: "thread_updated"; room: RoomInfo; data: ThreadUpdatedService }
+  | { type: "thread_resolved"; room: RoomInfo; data: ThreadResolvedService }
+  | { type: "thread_archived"; room: RoomInfo; data: ThreadArchivedService }
+  | { type: "category_created"; workspace: WorkspaceInfo; data: CategoryCreatedService }
+  | { type: "category_updated"; workspace: WorkspaceInfo; data: CategoryUpdatedService }
+  | { type: "category_deleted"; workspace: WorkspaceInfo; data: CategoryDeletedService }
+  | { type: "pin_added"; room: RoomInfo; data: PinAddedService }
+  | { type: "pin_removed"; room: RoomInfo; data: PinRemovedService }
+  | { type: "workspace_room_created"; workspace: WorkspaceInfo; data: WorkspaceRoomCreatedService }
+  | { type: "workspace_room_deleted"; workspace: WorkspaceInfo; data: WorkspaceRoomDeletedService }
+  | { type: "draft_saved"; room: RoomInfo; data: DraftSavedService }
+  | { type: "draft_cleared"; room: RoomInfo; data: DraftClearedService }
+  | { type: "search_result"; data: SearchResultService }
+  | { type: "notify_created"; data: NotifyCreatedService }
+  | { type: "notify_read"; data: NotifyReadService }
+  | { type: "presence_changed"; data: PresenceChangedService }
+  | { type: "custom_status_updated"; data: CustomStatusUpdatedService }
+  | { type: "invite_created"; data: InviteCreatedService }
+  | { type: "invite_accepted"; data: InviteAcceptedService }
+  | { type: "attachment_uploaded"; data: AttachmentUploadedService }
+  | { type: "user_banned"; data: BannedService }
+  | { type: "user_unbanned"; data: UnbannedService }
+  | { type: "ai_agent_joined"; data: AiAgentJoinedService }
+  | { type: "ai_agent_left"; data: AiAgentLeftService }
+  | { type: "ai_agent_list"; room: RoomInfo; data: RoomAiListService }
+  | { type: "ai_agent_status_changed"; data: AiAgentStatusChangedService }
+  | { type: "voice_channel_joined"; data: VoiceChannelJoinedService }
+  | { type: "voice_channel_left"; data: VoiceChannelLeftService }
+  | { type: "conversation_pinned"; room: RoomInfo; data: ConversationPinnedService }
+  | { type: "conversation_unpinned"; room: RoomInfo; data: ConversationUnpinnedService }
+  | { type: "conversation_muted"; room: RoomInfo; data: ConversationMutedService }
+  | { type: "conversation_unmuted"; room: RoomInfo; data: ConversationUnmutedService }
+  | { type: "conversation_unread_updated"; room: RoomInfo; data: ConversationUnreadUpdatedService }
+  | { type: "conversation_list"; data: ConversationSummary[] }
+  | { type: "dm_created"; room: RoomInfo; data: DmCreatedService }
+  | { type: "dm_closed"; room: RoomInfo; data: DmClosedService }
+  | { type: "dm_reopened"; room: RoomInfo; data: DmReopenedService }
+  | { type: "dm_list"; data: DmCreatedService[] }
+  | { type: "message_read"; room: RoomInfo; data: MessageReadService }
+  | { type: "message_read_batch"; room: RoomInfo; data: MessageReadBatchService }
+  | { type: "message_readers"; data: MessageReadersService }
+  | { type: "message_starred"; room: RoomInfo; data: MessageStarredService }
+  | { type: "message_unstarred"; room: RoomInfo; data: MessageUnstarredService }
+  | { type: "starred_list"; data: StarredMessageEntry[] }
+  | { type: "message_forwarded"; room: RoomInfo; data: MessageForwardedService }
+  | { type: "response"; request_id: string; data: unknown };
\ No newline at end of file
diff --git a/src/socket/state.ts b/src/socket/state.ts
new file mode 100644
index 0000000..78c878d
--- /dev/null
+++ b/src/socket/state.ts
@@ -0,0 +1,19 @@
+import { createStore } from "zustand/vanilla";
+import { useStore } from "zustand";
+
+import type { ChannelSocketState } from "./types";
+
+export const channelSocketStore = createStore<ChannelSocketState>(() => ({
+  status: "idle",
+  transport: "unknown",
+  connected: false,
+  inFlight: 0,
+  queued: 0,
+  lastError: null,
+}));
+
+export function useChannelSocketState<T = ChannelSocketState>(
+  selector: (state: ChannelSocketState) => T = (state) => state as T,
+): T {
+  return useStore(channelSocketStore, selector);
+}
diff --git a/src/socket/subscription.ts b/src/socket/subscription.ts
new file mode 100644
index 0000000..48e2c77
--- /dev/null
+++ b/src/socket/subscription.ts
@@ -0,0 +1,53 @@
+/**
+ * Room subscription manager — tracks active room subscriptions,
+ * auto-subscribes on reconnect.
+ */
+export class RoomSubscriptionManager {
+  private subscriptions = new Set<string>();
+  private onSubscribe: ((roomId: string) => void) | null = null;
+  private onUnsubscribe: ((roomId: string) => void) | null = null;
+
+  /** Register callbacks for subscribe/unsubscribe actions. */
+  setCallbacks(
+    onSubscribe: (roomId: string) => void,
+    onUnsubscribe: (roomId: string) => void,
+  ): void {
+    this.onSubscribe = onSubscribe;
+    this.onUnsubscribe = onUnsubscribe;
+  }
+
+  subscribe(roomId: string): void {
+    if (this.subscriptions.has(roomId)) return;
+    this.subscriptions.add(roomId);
+    this.onSubscribe?.(roomId);
+  }
+
+  unsubscribe(roomId: string): void {
+    if (!this.subscriptions.has(roomId)) return;
+    this.subscriptions.delete(roomId);
+    this.onUnsubscribe?.(roomId);
+  }
+
+  /** Re-subscribe all rooms (used after reconnect). */
+  resubscribeAll(): void {
+    for (const roomId of this.subscriptions) {
+      this.onSubscribe?.(roomId);
+    }
+  }
+
+  isSubscribed(roomId: string): boolean {
+    return this.subscriptions.has(roomId);
+  }
+
+  getSubscribedRooms(): string[] {
+    return [...this.subscriptions];
+  }
+
+  get count(): number {
+    return this.subscriptions.size;
+  }
+
+  clear(): void {
+    this.subscriptions.clear();
+  }
+}
diff --git a/src/socket/types.ts b/src/socket/types.ts
new file mode 100644
index 0000000..29d6956
--- /dev/null
+++ b/src/socket/types.ts
@@ -0,0 +1,72 @@
+export type ChannelConnectionStatus =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "disconnected"
+  | "error";
+
+export type ChannelTransport = "websocket" | "polling" | "http" | "unknown";
+
+export type ChannelMessage = {
+  type: string;
+  _request_id?: string;
+  [key: string]: unknown;
+};
+
+export type ChannelErrorPayload = {
+  type?: "error";
+  code?: number;
+  error?: string;
+  message?: string;
+};
+
+export type ChannelResponse<T = unknown> = {
+  type: "response";
+  request_id: string;
+  data: T | ChannelErrorPayload;
+};
+
+export type ChannelOutEvent = import("./schema").WsOutEvent;
+
+export type ChannelRequestOptions = {
+  timeoutMs?: number;
+  fallback?: boolean;
+};
+
+export type ChannelSocketOptions = {
+  url?: string;
+  namespace?: string;
+  path?: string;
+  restBasePath?: string;
+  eventName?: string;
+  windowSize?: number;
+  timeoutMs?: number;
+  fallback?: boolean;
+  autoConnect?: boolean;
+};
+
+export type ChannelSocketState = {
+  status: ChannelConnectionStatus;
+  transport: ChannelTransport;
+  connected: boolean;
+  inFlight: number;
+  queued: number;
+  lastError: string | null;
+};
+
+export type ChannelEventHandler = (
+  event: ChannelOutEvent,
+) => void;
+
+// --- WS token auth types ---
+export type WsTokenRequest = {
+  device_id: string;
+  client_id: string;
+};
+
+export type WsTokenResponse = {
+  access_token: string;
+  expires_in_secs: number;
+};
+