chore(release): 1.16.0 [skip ci]

# [1.16.0](https://github.com/asepharyana/zesdex/compare/v1.15.2...v1.16.0) (2026-07-20) ### Features * **tui:** add usage overlay and sidebar for displaying usage statistics and tasks ([da2ed6d](https://github.com/asepharyana/zesdex/commit/da2ed6da25953b823354cc5deaa7b404b7b13cb0)) * **tui:** enhance agent turn with tool descriptions and sanitize arguments ([08e2f99](https://github.com/asepharyana/zesdex/commit/08e2f9998d3693e4cd57225491359c762d03f1d9)) * **tui:** implement agent turn engine for background processing and enhance input handling ([792695b](https://github.com/asepharyana/zesdex/commit/792695b65a393cfc54efe353480b7831e91544b5))
feat(tui): enhance agent turn with tool descriptions and sanitize arguments
2026-07-20 04:33:19 +00:00 · 2026-07-20 11:29:33 +07:00 · 2026-07-20 10:55:09 +07:00 · 2026-07-20 09:04:57 +07:00 · 2026-07-20 07:02:55 +07:00 · 2026-07-20 06:53:01 +07:00
462 changed files with 16820 additions and 25733 deletions
@@ -1,3 +1,19 @@
+# [1.16.0](https://github.com/asepharyana/zesdex/compare/v1.15.2...v1.16.0) (2026-07-20)
+
+
+### Features
+
+* **tui:** add usage overlay and sidebar for displaying usage statistics and tasks ([da2ed6d](https://github.com/asepharyana/zesdex/commit/da2ed6da25953b823354cc5deaa7b404b7b13cb0))
+* **tui:** enhance agent turn with tool descriptions and sanitize arguments ([08e2f99](https://github.com/asepharyana/zesdex/commit/08e2f9998d3693e4cd57225491359c762d03f1d9))
+* **tui:** implement agent turn engine for background processing and enhance input handling ([792695b](https://github.com/asepharyana/zesdex/commit/792695b65a393cfc54efe353480b7831e91544b5))
+
+## [1.15.2](https://github.com/asepharyana/zesdex/compare/v1.15.1...v1.15.2) (2026-07-17)
+
+
+### Bug Fixes
+
+* correct jitter range to ±25% and fix abort.rs doc — review findings ([9b6e51d](https://github.com/asepharyana/zesdex/commit/9b6e51dc677cc4b798532f1e63335785f2f7bbbf))
+
 ## [1.15.1](https://github.com/asepharyana/zesdex/compare/v1.15.0...v1.15.1) (2026-07-17)

 # [1.15.0](https://github.com/asepharyana/zesdex/compare/v1.14.0...v1.15.0) (2026-07-17)
@@ -32,6 +32,56 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.103"
@@ -134,6 +184,7 @@ checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
 dependencies = [
 "axum-core",
 "axum-macros",
+ "base64",
 "bytes",
 "form_urlencoded",
 "futures-util",
@@ -152,8 +203,10 @@ dependencies = [
 "serde_json",
 "serde_path_to_error",
 "serde_urlencoded",
+ "sha1",
 "sync_wrapper",
 "tokio",
+ "tokio-tungstenite",
 "tower",
 "tower-layer",
 "tower-service",
@@ -401,6 +454,46 @@ dependencies = [
 "windows-link",
 ]

+[[package]]
+name = "clap"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd059f9da4f5c36b3787f65d38ccaab1cc315f07b01f89abc8359ee6a8205011"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
 [[package]]
 name = "cmake"
 version = "0.1.58"
@@ -410,6 +503,12 @@ dependencies = [
 "cc",
 ]

+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
 [[package]]
 name = "combine"
 version = "4.6.7"
@@ -669,6 +768,12 @@ dependencies = [
 "syn 2.0.118",
 ]

+[[package]]
+name = "data-encoding"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"
+
 [[package]]
 name = "deltae"
 version = "0.3.2"
@@ -1624,6 +1729,12 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"

+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
 [[package]]
 name = "itertools"
 version = "0.14.0"
@@ -1937,6 +2048,16 @@ version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"

+[[package]]
+name = "mime_guess"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
+dependencies = [
+ "mime",
+ "unicase",
+]
+
 [[package]]
 name = "minimal-lexical"
 version = "0.2.1"
@@ -2142,6 +2263,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"

+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
 [[package]]
 name = "openssl"
 version = "0.10.81"
@@ -2483,6 +2610,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"

+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
 [[package]]
 name = "precomputed-hash"
 version = "0.1.1"
@@ -2619,6 +2755,16 @@ dependencies = [
 "rand_core 0.6.4",
 ]

+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "rand"
 version = "0.10.2"
@@ -2630,6 +2776,16 @@ dependencies = [
 "rand_core 0.10.1",
 ]

+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "rand_core"
 version = "0.6.4"
@@ -2639,6 +2795,15 @@ dependencies = [
 "getrandom 0.2.17",
 ]

+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
 [[package]]
 name = "rand_core"
 version = "0.10.1"
@@ -3249,6 +3414,17 @@ dependencies = [
 "stable_deref_trait",
 ]

+[[package]]
+name = "sha1"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
 [[package]]
 name = "sha1_smol"
 version = "1.0.1"
@@ -3849,6 +4025,18 @@ dependencies = [
 "tokio",
 ]

+[[package]]
+name = "tokio-tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -3977,6 +4165,22 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"

+[[package]]
+name = "tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand 0.9.5",
+ "sha1",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "typenum"
 version = "1.20.1"
@@ -4609,6 +4813,26 @@ dependencies = [
 "synstructure",
 ]

+[[package]]
+name = "zerocopy"
+version = "0.8.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "zerofrom"
 version = "0.1.8"
@@ -4670,14 +4894,157 @@ dependencies = [
 ]

 [[package]]
-name = "zesdex-backend"
-version = "1.15.1"
+name = "zesdex-api"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "argon2",
+ "axum",
+ "chrono",
+ "futures-util",
+ "jsonwebtoken",
+ "serde",
+ "serde_json",
+ "thiserror 1.0.69",
+ "tokio",
+ "tower",
+ "tower-http",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-application"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "base64",
+ "chrono",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tracing",
+ "url",
+ "uuid",
+ "zesdex-domain",
+]
+
+[[package]]
+name = "zesdex-bootstrap"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "chrono",
+ "dirs",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-daemon"
+version = "1.16.0"
 dependencies = [
 "anyhow",
 "base64",
 "chrono",
 "crossterm",
 "dirs",
+ "hex",
+ "ignore",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tracing",
+ "uuid",
+ "webbrowser",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-domain"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "base64",
+ "chrono",
+ "libc",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tracing",
+ "url",
+ "uuid",
+]
+
+[[package]]
+name = "zesdex-gateway"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "clap",
+ "dirs",
+ "rusqlite",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+ "uuid",
+ "zesdex-api",
+ "zesdex-application",
+ "zesdex-daemon",
+ "zesdex-domain",
+ "zesdex-grpc",
+ "zesdex-infrastructure",
+ "zesdex-tui",
+ "zesdex-web",
+ "zesdex-ws",
+]
+
+[[package]]
+name = "zesdex-grpc"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-infrastructure"
+version = "1.16.0"
+dependencies = [
+ "anyhow",
+ "argon2",
+ "axum",
+ "base64",
+ "chrono",
+ "clap",
+ "dirs",
 "dom_smoothie",
 "fast_html2md",
 "futures-util",
@@ -4686,12 +5053,13 @@ dependencies = [
 "ignore",
 "include_dir",
 "infer",
+ "jsonwebtoken",
 "libc",
 "lsp-types",
 "nucleo-matcher",
 "percent-encoding",
 "pulldown-cmark",
- "ratatui",
+ "rand_core 0.6.4",
 "regex",
 "reqwest",
 "rmcp",
@@ -4705,140 +5073,78 @@ dependencies = [
 "syntect",
 "tiktoken-rs",
 "tokio",
+ "tower",
+ "tower-http",
 "tracing",
- "tracing-subscriber",
 "url",
 "uuid",
 "webbrowser",
- "zesdex-cms",
- "zesdex-entities",
- "zesdex-iam",
- "zesdex-infra",
- "zesdex-ipc",
- "zesdex-middleware",
- "zesdex-utils",
+ "zesdex-application",
+ "zesdex-domain",
 ]

 [[package]]
-name = "zesdex-cms"
-version = "1.15.1"
-dependencies = [
- "anyhow",
- "chrono",
- "dirs",
- "hex",
- "serde",
- "serde_json",
- "tracing",
- "uuid",
- "zesdex-entities",
- "zesdex-utils",
-]
-
-[[package]]
-name = "zesdex-entities"
-version = "1.15.1"
+name = "zesdex-tui"
+version = "1.16.0"
 dependencies = [
 "anyhow",
 "base64",
 "chrono",
+ "crossterm",
 "dirs",
- "libc",
- "reqwest",
- "serde",
- "serde_json",
- "sha2 0.11.0",
- "tokio",
- "tracing",
- "url",
- "uuid",
-]
-
-[[package]]
-name = "zesdex-iam"
-version = "1.15.1"
-dependencies = [
- "anyhow",
- "base64",
- "chrono",
 "hex",
- "libc",
- "rand_core 0.6.4",
- "reqwest",
- "serde",
- "serde_json",
- "sha2 0.11.0",
- "tracing",
- "url",
- "uuid",
- "zesdex-entities",
- "zesdex-utils",
-]
-
-[[package]]
-name = "zesdex-infra"
-version = "1.15.1"
-dependencies = [
- "anyhow",
- "argon2",
- "axum",
- "chrono",
- "jsonwebtoken",
- "rand_core 0.6.4",
+ "nucleo-matcher",
+ "pulldown-cmark",
+ "ratatui",
 "rusqlite",
 "serde",
 "serde_json",
+ "sha2 0.11.0",
+ "tiktoken-rs",
 "tokio",
 "tracing",
 "uuid",
- "zesdex-cms",
- "zesdex-entities",
- "zesdex-iam",
- "zesdex-middleware",
- "zesdex-utils",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
 ]

 [[package]]
-name = "zesdex-ipc"
-version = "1.15.1"
-dependencies = [
- "anyhow",
- "serde",
- "serde_json",
- "tracing",
- "zesdex-entities",
-]
-
-[[package]]
-name = "zesdex-middleware"
-version = "1.15.1"
+name = "zesdex-web"
+version = "1.16.0"
 dependencies = [
 "anyhow",
 "axum",
 "chrono",
+ "include_dir",
+ "mime_guess",
 "serde",
 "serde_json",
+ "tokio",
 "tower",
- "tower-http",
- "zesdex-entities",
- "zesdex-utils",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
 ]

 [[package]]
-name = "zesdex-utils"
-version = "1.15.1"
+name = "zesdex-ws"
+version = "1.16.0"
 dependencies = [
 "anyhow",
- "base64",
+ "axum",
 "chrono",
- "dirs",
- "hex",
+ "futures-util",
 "serde",
 "serde_json",
- "sha2 0.11.0",
- "thiserror 1.0.69",
+ "tokio",
 "tracing",
- "tracing-subscriber",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
 ]

 [[package]]
@@ -1,18 +1,21 @@
 [workspace]
 resolver = "2"
 members = [
-    "crates/zesdex-entities",
-    "crates/zesdex-utils",
-    "crates/zesdex-ipc",
-    "crates/zesdex-iam",
-    "crates/zesdex-cms",
-    "crates/zesdex-middleware",
-    "crates/zesdex-infra",
-    "crates/zesdex-backend",
+    "apps/domain",
+    "apps/application",
+    "apps/infrastructure",
+    "apps/interfaces/tui",
+    "apps/interfaces/api",
+    "apps/interfaces/daemon",
+    "apps/interfaces/ws",
+    "apps/interfaces/grpc",
+    "apps/interfaces/web",
+    "apps/gateway",
+    "apps/bootstrap",
 ]

 [workspace.package]
-version = "1.15.1"
+version = "1.16.0"
 edition = "2021"
 authors = ["asepharyana <superaseph@gmail.com>"]

@@ -76,6 +79,18 @@ tower = "0.5"
 tower-http = { version = "0.6", features = ["cors", "limit"] }
 argon2 = "0.5"
 jsonwebtoken = "9"
+clap = { version = "4", features = ["derive"] }
+rand_core = { version = "0.6", features = ["getrandom"] }

-zesdex-entities = { path = "crates/zesdex-entities" }
-zesdex-utils = { path = "crates/zesdex-utils" }
+# Clean-architecture workspace crate references
+zesdex-domain = { path = "apps/domain" }
+zesdex-application = { path = "apps/application" }
+zesdex-infrastructure = { path = "apps/infrastructure" }
+zesdex-tui = { path = "apps/interfaces/tui" }
+zesdex-api = { path = "apps/interfaces/api" }
+zesdex-daemon = { path = "apps/interfaces/daemon" }
+zesdex-ws = { path = "apps/interfaces/ws" }
+zesdex-grpc = { path = "apps/interfaces/grpc" }
+zesdex-web = { path = "apps/interfaces/web" }
+zesdex-gateway = { path = "apps/gateway" }
+zesdex-bootstrap = { path = "apps/bootstrap" }
@@ -1,22 +1,21 @@
 [package]
-name = "zesdex-iam"
+name = "zesdex-application"
 version.workspace = true
 edition.workspace = true
 authors.workspace = true

+# Application layer — port traits (interfaces), use cases, DTOs.
+# Depends ONLY on domain. Application services orchestrate domain objects
+# through port traits without knowing concrete implementations.
 [dependencies]
+zesdex-domain = { path = "../domain" }
 serde.workspace = true
 serde_json.workspace = true
-anyhow.workspace = true
 chrono.workspace = true
 uuid.workspace = true
-zesdex-entities = { path = "../zesdex-entities" }
-zesdex-utils = { path = "../zesdex-utils" }
-reqwest.workspace = true
-libc.workspace = true
+anyhow.workspace = true
 tracing.workspace = true
-url.workspace = true
+tokio.workspace = true
 base64.workspace = true
 sha2.workspace = true
-hex.workspace = true
-rand_core = { version = "0.6", features = ["getrandom"] }
+url.workspace = true
@@ -0,0 +1,16 @@
+//! Auth use-case implementations.
+//!
+//! Contains concrete service types that implement the domain's
+//! authentication and session management traits by coordinating
+//! injected repository and port dependencies.
+//!
+//! # Use Cases
+//!
+//! - [`oauth_service`] — `OAuthUseCase`: OAuth 2.0 authorization-code + PKCE flow
+//! - [`session_service`] — `SessionServiceImpl`: session CRUD lifecycle
+
+pub mod oauth_service;
+pub mod session_service;
+
+pub use oauth_service::{OAuthFlowStore, OAuthUseCase, TokenExchanger};
+pub use session_service::SessionServiceImpl;
@@ -0,0 +1,250 @@
+//! OAuth 2.0 authorization-code + PKCE flow use-case.
+//!
+//! `OAuthUseCase` orchestrates the standard PKCE-enhanced OAuth flow:
+//!
+//! 1. **`start_flow`** — generates a cryptographic PKCE code verifier,
+//!    derives its S256 challenge, creates a CSRF state token, persists
+//!    the verifier + state via `OAuthFlowStore`, and builds an
+//!    authorization URL with all required parameters.
+//! 2. **`complete_flow`** — validates the returned `state` against the
+//!    stored value (CSRF check), reads the stored verifier, delegates
+//!    the token-code exchange to an injected `TokenExchanger`, and
+//!    persists the resulting `OAuthToken` via `OAuthRepository`.
+//! 3. **`get_token`** — loads the stored OAuth token (if any).
+//!
+//! # Portability
+//!
+//! The service is generic over three injected dependencies:
+//! - `R: OAuthRepository` — token persistence
+//! - `S: OAuthFlowStore` — ephemeral flow state (verifier + CSRF state)
+//! - `E: TokenExchanger` — the HTTP token-endpoint exchange
+//!
+//! This keeps all I/O and protocol-level concerns abstracted behind
+//! port traits; the service itself contains only orchestration logic.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::auth::{OAuthConfig, OAuthRepository, OAuthToken, ServiceError};
+
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine as _;
+use sha2::{Digest, Sha256};
+
+// ---------------------------------------------------------------------------
+// Port traits (defined here because they are specific to this use-case)
+// ---------------------------------------------------------------------------
+
+/// Persistence contract for ephemeral OAuth flow state.
+///
+/// Between `start_flow` and `complete_flow` the verifier and CSRF state
+/// must survive across process boundaries (the user opens a browser, the
+/// provider redirects back to a loopback listener on the next invocation).
+///
+/// Implementors store key-value pairs to disk or another durable medium
+/// and clear them after a successful (or failed) flow completion.
+pub trait OAuthFlowStore: Send + Sync {
+    /// Persist the PKCE code verifier and CSRF state token.
+    fn save_flow_state(
+        &self,
+        verifier: &str,
+        state: &str,
+    ) -> Result<(), ServiceError>;
+
+    /// Load the stored PKCE code verifier.
+    fn load_verifier(&self) -> Result<String, ServiceError>;
+
+    /// Load the stored CSRF state token.
+    fn load_state(&self) -> Result<String, ServiceError>;
+
+    /// Clear stored flow state (verifier + state).
+    fn clear(&self) -> Result<(), ServiceError>;
+}
+
+/// Abstraction for exchanging an authorization code for tokens.
+///
+/// Implementors handle the HTTP POST to the provider's token endpoint
+/// with the appropriate form-encoded parameters, parse the JSON
+/// response, and return the extracted `OAuthToken`.
+pub trait TokenExchanger: Send + Sync {
+    /// Exchange an authorization code for an access token.
+    ///
+    /// ## Parameters
+    /// - `token_url` — the provider's token endpoint URL
+    /// - `client_id` — OAuth client identifier
+    /// - `client_secret` — optional client secret
+    /// - `redirect_uri` — must match the URI used in `start_flow`
+    /// - `code` — the authorization code from the provider's redirect
+    /// - `code_verifier` — the PKCE verifier from `start_flow`
+    fn exchange_code(
+        &self,
+        token_url: &str,
+        client_id: &str,
+        client_secret: Option<&str>,
+        redirect_uri: &str,
+        code: &str,
+        code_verifier: &str,
+    ) -> Result<OAuthToken, ServiceError>;
+}
+
+// ---------------------------------------------------------------------------
+// PKCE helpers
+// ---------------------------------------------------------------------------
+
+/// Generate a PKCE code-verifier and its S256 code-challenge.
+///
+/// Uses 32 cryptographically random bytes, base64url-encoded (no padding)
+/// for the verifier, then SHA-256 hashes the verifier and base64url-encodes
+/// the digest for the challenge. This satisfies the PKCE `S256` method
+/// which requires a minimum verifier length of 43 characters.
+fn generate_pkce_pair() -> (String, String) {
+    // 32 random bytes → 43 base64url chars (well above the 43-char PKCE
+    // minimum).
+    let mut bytes = [0u8; 32];
+    bytes[..16].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
+    bytes[16..].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
+
+    let verifier = URL_SAFE_NO_PAD.encode(&bytes);
+    let challenge = {
+        let mut hasher = Sha256::new();
+        hasher.update(verifier.as_bytes());
+        URL_SAFE_NO_PAD.encode(hasher.finalize())
+    };
+    (verifier, challenge)
+}
+
+/// Generate a random CSRF state token (UUID-based, 36 chars).
+fn generate_state_token() -> String {
+    uuid::Uuid::new_v4().to_string()
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/// Concrete OAuth flow use-case.
+///
+/// Generic over three dependencies:
+/// - `R` — token persistence (`OAuthRepository`)
+/// - `S` — flow-state persistence (`OAuthFlowStore`)
+/// - `E` — token-endpoint HTTP exchange (`TokenExchanger`)
+pub struct OAuthUseCase<R, S, E> {
+    /// Repository for persisting / loading OAuth tokens.
+    pub token_repo: R,
+    /// Store for ephemeral flow state (verifier + CSRF state).
+    pub flow_store: S,
+    /// Token-endpoint HTTP exchanger.
+    pub token_exchanger: E,
+    /// File path for the token JSON file.
+    pub token_path: PathBuf,
+}
+
+impl<R: OAuthRepository, S: OAuthFlowStore, E: TokenExchanger> OAuthUseCase<R, S, E> {
+    /// Create a new OAuth use-case.
+    pub fn new(
+        token_repo: R,
+        flow_store: S,
+        token_exchanger: E,
+        token_path: PathBuf,
+    ) -> Self {
+        OAuthUseCase {
+            token_repo,
+            flow_store,
+            token_exchanger,
+            token_path,
+        }
+    }
+}
+
+impl<R: OAuthRepository, S: OAuthFlowStore, E: TokenExchanger>
+    zesdex_domain::auth::OAuthService for OAuthUseCase<R, S, E>
+{
+    fn start_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+    ) -> Result<(String, String), ServiceError> {
+        if config.auth_url.is_empty() {
+            return Err(ServiceError::InvalidConfig(
+                "OAuth auth_url is empty".to_string(),
+            ));
+        }
+
+        let (verifier, challenge) = generate_pkce_pair();
+        let state = generate_state_token();
+
+        // Persist verifier + state so `complete_flow` can retrieve them.
+        self.flow_store.save_flow_state(&verifier, &state)?;
+
+        tracing::debug!(
+            auth_url = %config.auth_url,
+            redirect_uri = %redirect_uri,
+            state_len = state.len(),
+            "starting OAuth flow",
+        );
+
+        let mut url = url::Url::parse(&config.auth_url)
+            .map_err(|e| {
+                ServiceError::InvalidConfig(format!(
+                    "invalid auth_url '{}': {e}",
+                    config.auth_url
+                ))
+            })?;
+
+        url.query_pairs_mut()
+            .append_pair("response_type", "code")
+            .append_pair("client_id", &config.client_id)
+            .append_pair("redirect_uri", redirect_uri)
+            .append_pair("scope", &config.scopes.join(" "))
+            .append_pair("state", &state)
+            .append_pair("code_challenge_method", "S256")
+            .append_pair("code_challenge", &challenge);
+
+        Ok((url.to_string(), state))
+    }
+
+    fn complete_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+        code: &str,
+        state: &str,
+    ) -> Result<OAuthToken, ServiceError> {
+        // CSRF check: validate the returned state against the stored value.
+        let expected_state = self.flow_store.load_state()?;
+        if expected_state != state {
+            return Err(ServiceError::StateMismatch);
+        }
+
+        // Read the PKCE verifier that was saved in `start_flow`.
+        let verifier = self.flow_store.load_verifier()?;
+
+        tracing::debug!(
+            token_url = %config.token_url,
+            code_len = code.len(),
+            "completing OAuth flow — exchanging code for token",
+        );
+
+        // Delegate the HTTP token exchange to the injected exchanger.
+        let token = self.token_exchanger.exchange_code(
+            &config.token_url,
+            &config.client_id,
+            config.client_secret.as_deref(),
+            redirect_uri,
+            code,
+            &verifier,
+        )?;
+
+        // Persist the token and clean up flow state.
+        self.token_repo.save_token(&self.token_path, &token)?;
+        let _ = self.flow_store.clear();
+
+        Ok(token)
+    }
+
+    fn get_token(&self) -> Result<Option<OAuthToken>, ServiceError> {
+        self.token_repo
+            .load_token(&self.token_path)
+            .map_err(ServiceError::Repository)
+    }
+}
@@ -0,0 +1,89 @@
+//! Session management use-case.
+//!
+//! `SessionServiceImpl` implements [`SessionService`] from the domain
+//! layer by delegating CRUD operations to injected repository traits.
+//!
+//! # Flow
+//!
+//! - **`create_session`** — generates a UUID v4 id, creates a `Session`
+//!   entity with the given title, persists via `SessionRepository`.
+//! - **`list_all`** — delegates to `SessionRepository::list_sessions`.
+//! - **`archive_session`** — loads session, sets `archived = true`,
+//!   persists the updated entity.
+//!
+//! # Generics
+//!
+//! - `R: SessionRepository` — session CRUD persistence
+//! - `L: SessionLockRepository` — session lock acquire/release
+
+use std::path::PathBuf;
+use tracing;
+use uuid::Uuid;
+
+use zesdex_domain::auth::{
+    ServiceError, Session, SessionId, SessionLockRepository, SessionRepository,
+};
+
+/// Concrete session service backed by injected repository implementations.
+pub struct SessionServiceImpl<R: SessionRepository, L: SessionLockRepository> {
+    /// Repository for session CRUD operations.
+    pub session_repo: R,
+    /// Repository for session lock acquire/release.
+    pub lock_repo: L,
+    /// Base data directory passed to repository methods.
+    pub base_dir: PathBuf,
+}
+
+impl<R: SessionRepository, L: SessionLockRepository> SessionServiceImpl<R, L> {
+    /// Create a new session service with the given repositories and base
+    /// data directory.
+    pub fn new(session_repo: R, lock_repo: L, base_dir: PathBuf) -> Self {
+        SessionServiceImpl {
+            session_repo,
+            lock_repo,
+            base_dir,
+        }
+    }
+}
+
+impl<R: SessionRepository, L: SessionLockRepository>
+    zesdex_domain::auth::SessionService for SessionServiceImpl<R, L>
+{
+    fn create_session(&self, title: &str) -> Result<Session, ServiceError> {
+        let id = SessionId::new(&Uuid::new_v4().to_string())
+            .map_err(|e| ServiceError::Other(e))?;
+        let title_owned = if title.is_empty() {
+            "New Session".to_string()
+        } else {
+            title.to_string()
+        };
+        let session = Session::new(id.into_string(), title_owned);
+        tracing::debug!(session_id = %session.id, title = %session.title, "creating new session");
+        self.session_repo
+            .save_session(&self.base_dir, &session)?;
+        Ok(session)
+    }
+
+    fn list_all(&self) -> Result<Vec<Session>, ServiceError> {
+        tracing::debug!("listing all sessions");
+        self.session_repo
+            .list_sessions(&self.base_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn archive_session(&self, id: SessionId) -> Result<(), ServiceError> {
+        tracing::debug!(session_id = %id, "archiving session");
+        let mut session = self
+            .session_repo
+            .load_session(&self.base_dir, &id)?;
+        session.archived = true;
+        let millis = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis();
+        session.updated_at = i64::try_from(millis).unwrap_or(i64::MAX);
+        self.session_repo
+            .save_session(&self.base_dir, &session)?;
+        Ok(())
+    }
+}
@@ -0,0 +1,72 @@
+//! Conversation use-case implementation.
+//!
+//! `ConversationServiceImpl` implements [`ConversationService`] from the
+//! domain layer. It is generic over `R: ConversationRepository`, delegating
+//! all persistence to that adapter.
+//!
+//! # Flow
+//!
+//! Each method computes the session directory from the session ID, then
+//! delegates the actual I/O to the injected `repo`. Error context is
+//! added at this layer to identify which session caused the failure.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{Conversation, ConversationRepository, ServiceError};
+use zesdex_domain::core::ChatMessage;
+
+/// Service implementation for conversation CRUD operations.
+///
+/// Generic over `R: ConversationRepository` so the persistence layer
+/// can be swapped without changing business logic.
+pub struct ConversationServiceImpl<R> {
+    pub repo: R,
+    /// Base directory containing session subdirectories.
+    pub sessions_dir: PathBuf,
+}
+
+impl<R: ConversationRepository> ConversationServiceImpl<R> {
+    /// Create a new service with the given repository and sessions directory.
+    pub fn new(repo: R, sessions_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating ConversationServiceImpl");
+        Self {
+            repo,
+            sessions_dir: sessions_dir.into(),
+        }
+    }
+
+    /// Compute the session directory for a given session id.
+    fn session_dir(&self, session_id: &str) -> PathBuf {
+        self.sessions_dir.join(session_id)
+    }
+}
+
+impl<R: ConversationRepository> zesdex_domain::cms::ConversationService
+    for ConversationServiceImpl<R>
+{
+    fn load_conversation(&self, session_id: &str) -> Result<Conversation, ServiceError> {
+        tracing::debug!("loading conversation for session {session_id}");
+        let dir = self.session_dir(session_id);
+        self.repo.load(&dir).map_err(ServiceError::Repository)
+    }
+
+    fn save_conversation(&self, conv: &Conversation) -> Result<(), ServiceError> {
+        tracing::debug!("saving conversation for session {}", conv.session_id);
+        let dir = self.session_dir(&conv.session_id);
+        self.repo.save(&dir, conv)?;
+        Ok(())
+    }
+
+    fn add_message(
+        &self,
+        conv: &mut Conversation,
+        msg: ChatMessage,
+    ) -> Result<(), ServiceError> {
+        tracing::debug!("adding message to session {}", conv.session_id);
+        conv.push(msg);
+        let dir = self.session_dir(&conv.session_id);
+        self.repo.save(&dir, conv)?;
+        Ok(())
+    }
+}
@@ -0,0 +1,59 @@
+//! Memory use-case implementation.
+//!
+//! `MemoryServiceImpl` implements [`MemoryService`] from the domain
+//! layer. It is generic over `R: MemoryRepository`, delegating all
+//! persistence to that adapter.
+//!
+//! # Flow
+//!
+//! Each method delegates to the injected `repo` with the configured
+//! `memory_dir`. Error context is added at this layer to identify which
+//! memory operation failed.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{Memory, MemoryRepository, ServiceError};
+
+/// Service implementation for memory CRUD operations.
+///
+/// Generic over `R: MemoryRepository` so the persistence layer can be
+/// swapped without changing business logic.
+pub struct MemoryServiceImpl<R> {
+    pub repo: R,
+    /// Base directory for memory storage files.
+    pub memory_dir: PathBuf,
+}
+
+impl<R: MemoryRepository> MemoryServiceImpl<R> {
+    /// Create a new service with the given repository and memory directory.
+    pub fn new(repo: R, memory_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating MemoryServiceImpl");
+        Self {
+            repo,
+            memory_dir: memory_dir.into(),
+        }
+    }
+}
+
+impl<R: MemoryRepository> zesdex_domain::cms::MemoryService for MemoryServiceImpl<R> {
+    fn list_memories(&self) -> Result<Vec<String>, ServiceError> {
+        tracing::debug!("listing memories from {:?}", self.memory_dir);
+        self.repo
+            .list(&self.memory_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn save_memory(&self, memory: &Memory) -> Result<(), ServiceError> {
+        tracing::debug!("saving memory '{}'", memory.name);
+        self.repo.save(&self.memory_dir, memory)?;
+        Ok(())
+    }
+
+    fn delete_memory(&self, name: &str) -> Result<(), ServiceError> {
+        tracing::debug!("deleting memory '{name}'");
+        self.repo
+            .delete(&self.memory_dir, name)
+            .map_err(ServiceError::Repository)
+    }
+}
@@ -0,0 +1,18 @@
+//! CMS use-case implementations.
+//!
+//! Contains concrete service types that implement the domain's CMS
+//! service traits by coordinating injected repository dependencies.
+//!
+//! # Use Cases
+//!
+//! - [`conversation_service`] — `ConversationServiceImpl`: conversation CRUD
+//! - [`memory_service`] — `MemoryServiceImpl`: long-term memory management
+//! - [`settings_service`] — `SettingsServiceImpl`: settings & app-config management
+
+pub mod conversation_service;
+pub mod memory_service;
+pub mod settings_service;
+
+pub use conversation_service::ConversationServiceImpl;
+pub use memory_service::MemoryServiceImpl;
+pub use settings_service::SettingsServiceImpl;
@@ -0,0 +1,76 @@
+//! Settings and app-config use-case implementation.
+//!
+//! `SettingsServiceImpl` implements [`SettingsService`] from the domain
+//! layer. It is generic over `S: SettingsRepository` and `C: AppConfigRepository`,
+//! delegating persistence to those adapters.
+//!
+//! # Flow
+//!
+//! Each method delegates to the appropriate injected repository with the
+//! configured `base_dir`. The `update_provider` method coordinates between
+//! both repositories: load app config → mutate provider map → save app config.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{
+    AppConfig, AppConfigRepository, ProviderConfig, ServiceError, Settings,
+    SettingsRepository,
+};
+
+/// Service implementation for settings and app-config operations.
+///
+/// Generic over `S: SettingsRepository` and `C: AppConfigRepository` so
+/// the persistence layer can be swapped without changing business logic.
+pub struct SettingsServiceImpl<S, C> {
+    pub settings_repo: S,
+    pub app_config_repo: C,
+    pub base_dir: PathBuf,
+}
+
+impl<S: SettingsRepository, C: AppConfigRepository> SettingsServiceImpl<S, C> {
+    /// Create a new service with the given repositories and base directory.
+    pub fn new(
+        settings_repo: S,
+        app_config_repo: C,
+        base_dir: impl Into<PathBuf>,
+    ) -> Self {
+        tracing::debug!("creating SettingsServiceImpl");
+        Self {
+            settings_repo,
+            app_config_repo,
+            base_dir: base_dir.into(),
+        }
+    }
+}
+
+impl<S: SettingsRepository, C: AppConfigRepository>
+    zesdex_domain::cms::SettingsService for SettingsServiceImpl<S, C>
+{
+    fn load_settings(&self) -> Result<Settings, ServiceError> {
+        tracing::debug!("loading settings");
+        self.settings_repo
+            .load(&self.base_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn save_settings(&self, settings: &Settings) -> Result<(), ServiceError> {
+        tracing::debug!("saving settings");
+        self.settings_repo.save(&self.base_dir, settings)?;
+        Ok(())
+    }
+
+    fn update_provider(
+        &self,
+        name: &str,
+        config: &ProviderConfig,
+    ) -> Result<(), ServiceError> {
+        tracing::debug!("updating provider '{name}'");
+        let mut app_config: AppConfig = self.app_config_repo.load(&self.base_dir)?;
+        app_config
+            .providers
+            .insert(name.to_string(), config.clone());
+        self.app_config_repo.save(&self.base_dir, &app_config)?;
+        Ok(())
+    }
+}
@@ -0,0 +1,51 @@
+//! # Zesdex Application Layer
+//!
+//! Defines port traits (interfaces) and use-case implementations for the
+//! Zesdex application. This crate depends **only** on the domain crate;
+//! it has no knowledge of infrastructure or interface adapters.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! apps/application/src/
+//! ├── lib.rs              — crate root, re-exports
+//! ├── ports/              — Port traits (interfaces to external services)
+//! │   ├── provider.rs     -- ProviderService (LLM chat completion)
+//! │   ├── password.rs     -- PasswordService (hash / verify)
+//! │   ├── token.rs        -- TokenService (JWT create / verify)
+//! │   └── authentication.rs -- AuthService (combined auth)
+//! ├── auth/               — Auth use-cases
+//! │   ├── oauth_service.rs   -- OAuth 2.0 PKCE flow
+//! │   └── session_service.rs -- Session CRUD lifecycle
+//! └── cms/                — CMS use-cases
+//!     ├── conversation_service.rs -- Conversation CRUD
+//!     ├── memory_service.rs       -- Long-term memory management
+//!     └── settings_service.rs     -- Settings & app-config management
+//! ```
+//!
+//! ## Key Design Principle
+//!
+//! Application services are generic over their repository/port dependencies.
+//! Concrete implementations are injected at the composition root, keeping
+//! the use-case logic independent of any specific persistence or infrastructure
+//! technology.
+
+pub mod auth;
+pub mod cms;
+pub mod ports;
+
+// Re-export port traits for ergonomic access.
+pub use ports::*;
+
+// Re-export auth use-cases.
+pub use auth::{
+    oauth_service::{OAuthFlowStore, OAuthUseCase, TokenExchanger},
+    session_service::SessionServiceImpl,
+};
+
+// Re-export CMS use-cases.
+pub use cms::{
+    conversation_service::ConversationServiceImpl,
+    memory_service::MemoryServiceImpl,
+    settings_service::SettingsServiceImpl,
+};
@@ -0,0 +1,35 @@
+//! AuthService port — combined authentication operations.
+//!
+//! Defines a high-level authentication trait that composes password
+//! verification and token generation into a single use-case boundary.
+//! Implementations delegate to the injected `PasswordService` and
+//! `TokenService` adapters.
+
+use anyhow::Result;
+use std::future::Future;
+
+/// High-level authentication service combining password verification
+/// and token issuance (login flow).
+///
+/// # Flow
+///
+/// 1. **`authenticate`** — verify a subject's password against a stored hash.
+/// 2. **`issue_tokens`** — generate an access + refresh token pair for a subject.
+///
+/// Implementations are generic over `PasswordService` and `TokenService`
+/// port traits.
+pub trait AuthService: Send + Sync {
+    /// Authenticate a user by verifying a password against a stored hash.
+    ///
+    /// Returns `true` if the password matches, `false` otherwise.
+    fn authenticate(
+        &self,
+        password: &str,
+        hash: &str,
+    ) -> impl Future<Output = Result<bool>> + Send;
+
+    /// Issue a new access + refresh token pair for the given subject.
+    ///
+    /// Returns `(access_token, refresh_token)`.
+    fn issue_tokens(&self, sub: &str) -> Result<(String, String)>;
+}
@@ -0,0 +1,22 @@
+//! Port traits — interfaces for external / infrastructure services.
+//!
+//! These traits define the boundaries between the application layer and
+//! the outside world. Infrastructure adapters implement these traits;
+//! the application layer depends only on the trait definitions.
+//!
+//! # Ports
+//!
+//! - [`provider`] — `ProviderService`: LLM chat completion (streaming + non-streaming)
+//! - [`password`] — `PasswordService`: password hashing and verification
+//! - [`token`] — `TokenService`: JWT access/refresh token generation and verification
+//! - [`authentication`] — `AuthService`: combined authentication operations
+
+pub mod authentication;
+pub mod password;
+pub mod provider;
+pub mod token;
+
+pub use authentication::AuthService;
+pub use password::PasswordService;
+pub use provider::ProviderService;
+pub use token::TokenService;
@@ -0,0 +1,24 @@
+//! PasswordService port — password hashing and verification abstraction.
+//!
+//! Defines the trait that password-hashing adapters (argon2, bcrypt, etc.)
+//! implement. The application layer depends only on this trait, never on
+//! a concrete hashing library.
+
+use anyhow::Result;
+use std::future::Future;
+
+/// Abstraction for password hashing and verification.
+///
+/// Implementors handle the actual hashing algorithm (argon2, bcrypt, etc.)
+/// and parameter selection. The trait is `Send + Sync` for use in async
+/// service layers.
+pub trait PasswordService: Send + Sync {
+    /// Hash a plaintext password and return the encoded hash string
+    /// (suitable for storage in a credential store).
+    fn hash(&self, password: &str) -> impl Future<Output = Result<String>> + Send;
+
+    /// Verify a plaintext password against a previously-hashed string.
+    ///
+    /// Returns `true` if the password matches the hash, `false` otherwise.
+    fn verify(&self, password: &str, hash: &str) -> impl Future<Output = Result<bool>> + Send;
+}
@@ -0,0 +1,56 @@
+//! ProviderService port — LLM chat completion provider abstraction.
+//!
+//! Defines the trait that HTTP-based provider clients (OpenAI, Anthropic,
+//! etc.) implement. Supports both non-streaming and SSE-streaming chat
+//! completion requests.
+//!
+//! # Flow
+//!
+//! 1. Caller builds a message list and optional tool definitions.
+//! 2. `chat` sends a non-streaming request and returns the full response.
+//! 3. `chat_stream` sends a streaming request and invokes `on_event` for
+//!    each parsed `StreamEvent` as it arrives, then returns the assembled
+//!    message and usage.
+
+use anyhow::Result;
+use std::future::Future;
+
+use zesdex_domain::core::{ChatMessage, StreamEvent, ToolDef};
+
+/// Abstraction for an LLM provider chat-completion service.
+///
+/// Both methods accept a message list, optional tool definitions, and
+/// generation parameters. Implementors handle authentication, HTTP
+/// transport, retry logic, and response parsing internally.
+///
+/// # Send + Sync
+///
+/// This trait is `Send + Sync` so it can be shared across async tasks
+/// and injected into service structs that require thread safety.
+pub trait ProviderService: Send + Sync {
+    /// Send a non-streaming chat completion request.
+    ///
+    /// Returns the assistant's `ChatMessage` and optional token usage
+    /// `(prompt_tokens, completion_tokens)`.
+    fn chat(
+        &self,
+        messages: &[ChatMessage],
+        tools: Option<Vec<ToolDef>>,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+    ) -> impl Future<Output = Result<(ChatMessage, Option<(u64, u64)>)>> + Send;
+
+    /// Send a streaming chat completion request.
+    ///
+    /// `on_event` is called for every parsed SSE event and returns `false`
+    /// to signal abort (caller cancellation). Returns the fully assembled
+    /// assistant message and optional usage once the stream completes.
+    fn chat_stream(
+        &self,
+        messages: &[ChatMessage],
+        tools: Option<Vec<ToolDef>>,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+        on_event: Box<dyn FnMut(&StreamEvent) -> bool + Send>,
+    ) -> impl Future<Output = Result<(ChatMessage, Option<(u64, u64)>)>> + Send;
+}
@@ -0,0 +1,26 @@
+//! TokenService port — JWT access and refresh token abstraction.
+//!
+//! Defines the trait that JWT adapter implementations provide. Covers
+//! token generation (pair of access + refresh tokens) and access token
+//! verification (returns the subject claim).
+
+use anyhow::Result;
+
+/// Abstraction for JWT-based token generation and verification.
+///
+/// Implementors handle signing key management, token serialisation,
+/// and expiry validation. The trait is `Send + Sync` for use across
+/// thread boundaries.
+pub trait TokenService: Send + Sync {
+    /// Generate an access + refresh token pair for the given subject
+    /// identifier.
+    ///
+    /// Returns `(access_token, refresh_token)`.
+    fn generate_tokens(&self, sub: &str) -> Result<(String, String)>;
+
+    /// Verify an access token and return the embedded subject claim.
+    ///
+    /// Returns `Err` if the token is expired, malformed, or has an
+    /// invalid signature.
+    fn verify_access_token(&self, token: &str) -> Result<String>;
+}
@@ -0,0 +1,25 @@
+[package]
+name = "zesdex-bootstrap"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+# Bootstrap binary — seeds initial system data (permissions, roles,
+# admin user) idempotently. Run once after first deployment.
+[[bin]]
+name = "bootstrap"
+path = "src/main.rs"
+
+[dependencies]
+zesdex-domain = { path = "../domain" }
+zesdex-application = { path = "../application" }
+zesdex-infrastructure = { path = "../infrastructure" }
+
+serde.workspace = true
+serde_json.workspace = true
+chrono.workspace = true
+uuid.workspace = true
+anyhow.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+dirs.workspace = true
@@ -0,0 +1,2 @@
+//! Bootstrap library — shared utilities for the bootstrap binary.
+//! The main entry point is in `main.rs`.
@@ -0,0 +1,38 @@
+//! Bootstrap binary — seeds initial system data idempotently.
+//!
+//! Creates default permissions, roles, and admin user if they don't
+//! already exist. Run once after first deployment.
+//!
+//! Usage: cargo run --bin bootstrap
+
+fn main() -> anyhow::Result<()> {
+    println!("Zesdex Bootstrap — seeding initial data...");
+
+    let store = zesdex_domain::core::Store::new();
+    store.ensure_dirs()?;
+
+    // Seed default settings if not present
+    let settings_path = store.base_dir.join("settings.json");
+    if !settings_path.exists() {
+        let settings = zesdex_domain::cms::Settings::default();
+        let content = serde_json::to_string_pretty(&settings)?;
+        std::fs::write(&settings_path, content)?;
+        println!("  ✓ Default settings created");
+    } else {
+        println!("  · Settings already exist, skipping");
+    }
+
+    // Seed default app config if not present
+    let config_path = store.base_dir.join("app_config.json");
+    if !config_path.exists() {
+        let config = zesdex_domain::cms::AppConfig::default();
+        let content = serde_json::to_string_pretty(&config)?;
+        std::fs::write(&config_path, content)?;
+        println!("  ✓ Default app_config created");
+    } else {
+        println!("  · App config already exists, skipping");
+    }
+
+    println!("Bootstrap complete.");
+    Ok(())
+}
@@ -1,20 +1,20 @@
 [package]
-name = "zesdex-entities"
+name = "zesdex-domain"
 version.workspace = true
 edition.workspace = true
 authors.workspace = true

+# Domain layer — PURE entities, value objects, repository/service traits.
+# Zero framework dependencies. Only serde for serialization, chrono for
+# timestamps, uuid for identity.
 [dependencies]
 serde.workspace = true
 serde_json.workspace = true
 chrono.workspace = true
 uuid.workspace = true
-anyhow.workspace = true
-dirs.workspace = true
-libc.workspace = true
 base64.workspace = true
 sha2.workspace = true
 url.workspace = true
-reqwest.workspace = true
-tokio.workspace = true
+libc.workspace = true
+anyhow.workspace = true
 tracing.workspace = true
@@ -0,0 +1,30 @@
+//! Command types for IAM domain operations.
+//!
+//! Following the `NewXxx` / command pattern from clean architecture,
+//! these types encapsulate the input data for create/update operations
+//! on domain entities. They decouple presentation DTOs from the entity
+//! mutation surface and provide a clear boundary for validation.
+
+/// Command to create a new session.
+///
+/// Carries only the data needed to construct a session entity — the
+/// service generates the UUID and timestamp internally.
+#[derive(Debug, Clone)]
+pub struct NewSession {
+    /// Human-readable session title.
+    pub title: String,
+}
+
+impl From<String> for NewSession {
+    fn from(title: String) -> Self {
+        Self { title }
+    }
+}
+
+impl From<&str> for NewSession {
+    fn from(title: &str) -> Self {
+        Self {
+            title: title.to_string(),
+        }
+    }
+}
@@ -0,0 +1,62 @@
+//! Domain error types for the IAM (auth) module.
+//!
+//! Typed error enums replace `anyhow::Result` in domain traits and
+//! application services, enabling callers to match on specific error
+//! variants (e.g. `NotFound` vs `Conflict`) rather than string-checking.
+//!
+//! # Components
+//!
+//! - [`RepositoryError`] — persistence-layer errors (not found, conflict, I/O)
+//! - [`ServiceError`] — use-case / orchestration errors (config, state
+//!   mismatch, provider failures)
+
+use std::fmt;
+
+use crate::error::DomainError;
+
+/// Shared repository error type for IAM persistence operations.
+pub type RepositoryError = DomainError;
+
+/// Errors from service / use-case operations in the IAM domain.
+#[derive(Debug)]
+pub enum ServiceError {
+    /// A repository operation failed.
+    Repository(DomainError),
+    /// The provided configuration is invalid.
+    InvalidConfig(String),
+    /// OAuth state mismatch — possible CSRF attack.
+    StateMismatch,
+    /// The OAuth provider returned an error.
+    OAuthProvider(String),
+    /// A generic error with a message.
+    Other(String),
+}
+
+impl From<DomainError> for ServiceError {
+    fn from(err: DomainError) -> Self {
+        ServiceError::Repository(err)
+    }
+}
+
+impl fmt::Display for ServiceError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ServiceError::Repository(err) => write!(f, "repository error: {err}"),
+            ServiceError::InvalidConfig(msg) => write!(f, "invalid configuration: {msg}"),
+            ServiceError::StateMismatch => {
+                write!(f, "OAuth state mismatch — possible CSRF attack")
+            }
+            ServiceError::OAuthProvider(msg) => write!(f, "OAuth provider error: {msg}"),
+            ServiceError::Other(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+impl std::error::Error for ServiceError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ServiceError::Repository(err) => Some(err),
+            _ => None,
+        }
+    }
+}
@@ -0,0 +1,12 @@
+//! IAM Session re-export.
+//!
+//! Re-exports `Session` from the auth module for consistent IAM-boundary
+//! imports. Consumers of the IAM module import `Session` from here rather
+//! than from the core session module directly, keeping the dependency
+//! internal and allowing the IAM crate to own its domain vocabulary.
+
+pub use super::session::Session;
+
+/// Alias for `Session` used in IAM contexts to distinguish from other
+/// session types in the system.
+pub type IamSession = Session;
@@ -0,0 +1,36 @@
+//! Authentication domain entities, commands, errors, and repository/service traits.
+//!
+//! Combines the session types from `zesdex-entities` (auth sub-module) with the
+//! IAM domain types (commands, OAuth, repository/service traits) from `zesdex-iam`.
+//!
+//! # Sub-modules
+//!
+//! - [`session`] — `Session` entity (session metadata)
+//! - [`session_id`] — `SessionId` value object (validated newtype)
+//! - [`session_lock`] — `SessionLock` RAII guard (PID-file lock)
+//! - [`oauth`] — `OAuthToken`, `OAuthConfig` entities
+//! - [`iam_session`] — Re-export of `Session` for IAM-boundary consistency
+//! - [`commands`] — `NewSession` command type
+//! - [`error`] — `RepositoryError`, `ServiceError` types
+//! - [`repository`] — `SessionRepository`, `SessionLockRepository`, `OAuthRepository`
+//! - [`service`] — `SessionService`, `OAuthService` traits
+
+pub mod commands;
+pub mod error;
+pub mod iam_session;
+pub mod oauth;
+pub mod repository;
+pub mod service;
+pub mod session;
+pub mod session_id;
+pub mod session_lock;
+
+pub use commands::NewSession;
+pub use error::{RepositoryError, ServiceError};
+pub use iam_session::IamSession;
+pub use oauth::{OAuthConfig, OAuthToken};
+pub use repository::{OAuthRepository, SessionLockRepository, SessionRepository};
+pub use service::{OAuthService, SessionService};
+pub use session::Session;
+pub use session_id::SessionId;
+pub use session_lock::SessionLock;
@@ -1,29 +1,38 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! Pure OAuth entities — no HTTP or persistence logic.
+//!
+//! # Components
+//!
+//! - [`OAuthToken`] — access token with optional refresh token, epoch expiry
+//! - [`OAuthConfig`] — provider configuration (auth URL, token URL, client id,
+//!   optional client secret, scopes)
 use serde::{Deserialize, Serialize};

 /// An OAuth 2.0 access token with optional refresh token and absolute
 /// expiry time (epoch seconds).
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OAuthToken {
+    /// The OAuth 2.0 access token string.
    pub access_token: String,
+    /// Optional refresh token for long-lived access.
    pub refresh_token: Option<String>,
+    /// Absolute expiry timestamp (epoch seconds since UNIX_EPOCH).
    pub expires_at: u64,
+    /// Token type, e.g. `"Bearer"`.
    pub token_type: String,
 }

 /// Static configuration for an OAuth provider.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OAuthConfig {
+    /// Authorization endpoint URL.
    pub auth_url: String,
+    /// Token exchange endpoint URL.
    pub token_url: String,
+    /// OAuth client identifier.
    pub client_id: String,
+    /// Optional client secret (not all flows require it).
    pub client_secret: Option<String>,
+    /// Space-separated list of requested scopes.
    pub scopes: Vec<String>,
 }

@@ -0,0 +1,57 @@
+//! Repository trait definitions (pure — no impls, no concrete persistence).
+//!
+//! Defines the repository contracts that infrastructure adapters implement.
+//! Following clean architecture, domain code depends only on these traits,
+//! not on concrete persistence libraries.
+//!
+//! # Traits
+//!
+//! - [`SessionRepository`] — CRUD for session metadata
+//! - [`SessionLockRepository`] — acquire/release/liveness for session locks
+//! - [`OAuthRepository`] — persist/load OAuth tokens
+
+use std::path::Path;
+
+use crate::auth::error::RepositoryError;
+use crate::auth::oauth::OAuthToken;
+use crate::auth::session::Session;
+use crate::auth::session_id::SessionId;
+
+/// Repository for loading, saving, listing, and deleting sessions.
+pub trait SessionRepository {
+    /// List all loadable sessions under `<base_dir>/sessions/`.
+    fn list_sessions(&self, base_dir: &Path) -> Result<Vec<Session>, RepositoryError>;
+
+    /// Load a single session by id.
+    fn load_session(&self, base_dir: &Path, id: &SessionId) -> Result<Session, RepositoryError>;
+
+    /// Save a session's metadata to disk.
+    fn save_session(&self, base_dir: &Path, session: &Session) -> Result<(), RepositoryError>;
+
+    /// Delete a session directory and all its contents.
+    fn delete_session(&self, base_dir: &Path, id: &SessionId) -> Result<(), RepositoryError>;
+}
+
+/// Repository for per-session PID-file advisory locks.
+pub trait SessionLockRepository {
+    /// Try to acquire the lock for a session directory.
+    /// Returns `true` if the lock was acquired, `false` if another live
+    /// process holds it.
+    fn try_lock(&self, session_dir: &Path) -> Result<bool, RepositoryError>;
+
+    /// Release the lock by removing the lock file.
+    fn unlock(&self, session_dir: &Path) -> Result<(), RepositoryError>;
+
+    /// Check whether a process with the given PID is alive.
+    fn is_alive(&self, pid: u32) -> bool;
+}
+
+/// Repository for persisting and loading OAuth tokens.
+pub trait OAuthRepository {
+    /// Persist an OAuth token to a JSON file.
+    fn save_token(&self, path: &Path, token: &OAuthToken) -> Result<(), RepositoryError>;
+
+    /// Load an OAuth token from a JSON file, returning `None` if the file
+    /// does not exist.
+    fn load_token(&self, path: &Path) -> Result<Option<OAuthToken>, RepositoryError>;
+}
@@ -1,24 +1,29 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! Service trait definitions — use-case interfaces for session management
 //! and OAuth flows.
-use crate::domain::oauth::{OAuthConfig, OAuthToken};
-use crate::domain::session::Session;
+//!
+//! These traits define the boundary between the application orchestration
+//! layer and the domain. Implementations live in the application layer.
+//!
+//! # Traits
+//!
+//! - [`SessionService`] — create, list, archive sessions
+//! - [`OAuthService`] — start PKCE flow, complete code exchange, retrieve token
+
+use crate::auth::error::ServiceError;
+use crate::auth::oauth::{OAuthConfig, OAuthToken};
+use crate::auth::session::Session;
+use crate::auth::session_id::SessionId;

 /// Session management use-case boundary.
 pub trait SessionService {
    /// Create a new session with a generated UUID and the given title.
-    fn create_session(&self, title: &str) -> anyhow::Result<Session>;
+    fn create_session(&self, title: &str) -> Result<Session, ServiceError>;

    /// List all available sessions.
-    fn list_all(&self) -> anyhow::Result<Vec<Session>>;
+    fn list_all(&self) -> Result<Vec<Session>, ServiceError>;

    /// Archive a session by id (sets `archived = true`).
-    fn archive_session(&self, id: &str) -> anyhow::Result<()>;
+    fn archive_session(&self, id: SessionId) -> Result<(), ServiceError>;
 }

 /// OAuth flow use-case boundary.
@@ -32,7 +37,7 @@ pub trait OAuthService {
        &self,
        config: &OAuthConfig,
        redirect_uri: &str,
-    ) -> anyhow::Result<(String, String)>;
+    ) -> Result<(String, String), ServiceError>;

    /// Complete the OAuth flow: validates `state` against the value
    /// persisted during `start_flow` (bailing on mismatch — this is the
@@ -44,8 +49,8 @@ pub trait OAuthService {
        redirect_uri: &str,
        code: &str,
        state: &str,
-    ) -> anyhow::Result<OAuthToken>;
+    ) -> Result<OAuthToken, ServiceError>;

    /// Retrieve the currently stored OAuth token (if any).
-    fn get_token(&self) -> anyhow::Result<Option<OAuthToken>>;
+    fn get_token(&self) -> Result<Option<OAuthToken>, ServiceError>;
 }
@@ -0,0 +1,71 @@
+//! Session metadata: id, title, workspace roots, and message/token counts,
+//! persisted as `session.json` per session directory.
+//!
+//! # Flow
+//!
+//! Created via [`Session::new`] → mutated in-memory → persisted via repository.
+//!
+//! # Components
+//!
+//! - `Session` struct — fields for all session metadata
+//! - `new` — timestamped constructor
+//! - `session_dir` / `conversation_path` — pure path computation
+use chrono::Utc;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+
+/// Metadata for one conversation session (distinct from the message
+/// history itself, which lives in `Conversation`/the msglog).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Session {
+    /// Unique session identifier (validated against path traversal in `load`).
+    pub id: String,
+    /// Epoch-millis timestamp of creation (`Utc::now().timestamp_millis()`).
+    pub created_at: i64,
+    /// Epoch-millis timestamp of last update.
+    pub updated_at: i64,
+    /// Human-readable title for the conversation.
+    pub title: String,
+    /// Model identifier string, e.g. `"anthropic/claude-opus-4-8"`.
+    pub model: String,
+    /// Workspace root directories associated with this session.
+    pub workspace_roots: Vec<PathBuf>,
+    /// Running count of messages in the conversation.
+    pub message_count: u32,
+    /// Running count of tokens consumed.
+    pub token_count: u32,
+    /// Soft-delete flag — archived sessions are hidden from the default list.
+    pub archived: bool,
+    /// Optional AI-generated conversation summary (used for compact context).
+    pub summary: Option<String>,
+}
+
+impl Session {
+    /// Create a new session with the given id/title, defaulting the
+    /// model, workspace root (current dir), and counters.
+    pub fn new(id: String, title: String) -> Self {
+        let now = Utc::now().timestamp_millis();
+        Session {
+            id,
+            created_at: now,
+            updated_at: now,
+            title,
+            model: "anthropic/claude-opus-4-8".to_string(),
+            workspace_roots: vec![std::env::current_dir().unwrap_or_default()],
+            message_count: 0,
+            token_count: 0,
+            archived: false,
+            summary: None,
+        }
+    }
+
+    /// Compute this session's directory under `<base_dir>/sessions/<id>`.
+    pub fn session_dir(&self, base_dir: &Path) -> PathBuf {
+        base_dir.join("sessions").join(&self.id)
+    }
+
+    /// Compute this session's `conversation.json` path.
+    pub fn conversation_path(&self, base_dir: &Path) -> PathBuf {
+        self.session_dir(base_dir).join("conversation.json")
+    }
+}
@@ -0,0 +1,106 @@
+//! Validated session identifier newtype.
+//!
+//! [`SessionId`] wraps a `String` that has been checked for path-traversal
+//! characters. Construction via `SessionId::new(str)` validates the input
+//! once; the guarantee is then enforced by the type system for all
+//! downstream use.
+//!
+//! # Validation rules
+//!
+//! - Must not be empty
+//! - Must only contain alphanumeric characters, hyphens, and underscores
+
+use serde::{Deserialize, Serialize};
+use std::fmt;
+use std::path::Path;
+use std::path::PathBuf;
+
+/// A validated session identifier.
+///
+/// Guarantees the inner string is non-empty and contains no path-traversal
+/// characters (`/`, `\\`, `..`) or other unsafe delimiters.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
+pub struct SessionId(String);
+
+impl SessionId {
+    /// Validate and construct a `SessionId`.
+    ///
+    /// Returns `Err(msg)` if the input contains path separators, `..`, or
+    /// is empty.
+    pub fn new(id: &str) -> Result<Self, String> {
+        if id.is_empty() {
+            return Err("session id must not be empty".to_string());
+        }
+        if id.contains('/') || id.contains('\\') || id.contains("..") {
+            return Err(format!(
+                "session id '{id}' must not contain path separators"
+            ));
+        }
+        Ok(SessionId(id.to_string()))
+    }
+
+    /// Return the underlying string.
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Return the underlying owned string.
+    pub fn into_string(self) -> String {
+        self.0
+    }
+
+    /// Append this session id as a component of `base_dir`, yielding
+    /// `base_dir / self.0`.
+    ///
+    /// Safe because the id has been validated to contain no path separators.
+    pub fn join_to(&self, base_dir: &Path) -> PathBuf {
+        base_dir.join(&self.0)
+    }
+}
+
+impl AsRef<str> for SessionId {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for SessionId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl From<SessionId> for String {
+    fn from(sid: SessionId) -> Self {
+        sid.0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_valid_uuids() {
+        assert!(SessionId::new("550e8400-e29b-41d4-a716-446655440000").is_ok());
+        assert!(SessionId::new("my-session_123").is_ok());
+    }
+
+    #[test]
+    fn test_rejects_path_traversal() {
+        assert!(SessionId::new("../etc/passwd").is_err());
+        assert!(SessionId::new("foo/../../bar").is_err());
+        assert!(SessionId::new("foo\\..\\bar").is_err());
+    }
+
+    #[test]
+    fn test_rejects_empty() {
+        assert!(SessionId::new("").is_err());
+    }
+
+    #[test]
+    fn test_into_string() {
+        let sid = SessionId::new("abc-123").unwrap();
+        assert_eq!(sid.into_string(), "abc-123");
+    }
+}
@@ -1,21 +1,32 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! PID-file based advisory lock preventing two processes from operating on
 //! the same session directory concurrently.
+//!
+//! # Flow
+//!
+//! [`SessionLock::new`] creates a handle → [`SessionLock::try_lock`] attempts
+//! atomic `O_CREAT|O_EXCL` creation. If the lock file already exists, the
+//! owning PID is checked via liveness verification. Stale locks are
+//! overwritten atomically (temp-file + rename + fsync). On [`Drop`],
+//! the lock file is removed automatically.
+//!
+//! # Components
+//!
+//! - `SessionLock` — RAII guard wrapping a lock file path and PID
+//! - `try_lock` — three-phase atomic acquire with stale-lock recovery
+//! - `unlock` / `Drop` — explicit and implicit release
 use std::fs;
 use std::io::Write;
 use std::path::{Path, PathBuf};
+use tracing;

 /// A PID-file lock (`<session_dir>/.lock`) tied to the current process,
 /// auto-removed on drop.
 #[derive(Debug)]
 pub struct SessionLock {
-    path: PathBuf,
-    pid: u32,
+    /// Path to the `.lock` file inside the session directory.
+    pub(crate) path: PathBuf,
+    /// Process ID that holds (or will hold) this lock.
+    pub(crate) pid: u32,
 }

 impl SessionLock {
@@ -32,14 +43,9 @@ impl SessionLock {
    ///
    /// Flow: try `O_CREAT | O_EXCL` via `create_new(true)` → if that
    /// succeeds, the lock is ours — write our PID and return ok. If the
-    /// file already exists, read the PID inside it and check `is_alive`:
-    /// if that process is still running, fail to acquire; otherwise the
-    /// lock is stale — overwrite it with our own PID and succeed.
-    ///
-    /// Why: `create_new(true)` is atomic on POSIX (unlike the previous
-    /// read-then-write pattern which had a TOCTOU race between checking
-    /// `path.exists()` and writing). The stale-lock recovery path reads
-    /// the stale PID and verifies liveness via `kill(pid, 0)`.
+    /// file already exists, read the PID inside it and check whether that
+    /// PID is still alive: if the process is still running, fail to acquire;
+    /// otherwise the lock is stale — overwrite it with our own PID and succeed.
    ///
    /// Return: `Ok(true)` if acquired, `Ok(false)` if another live
    /// process holds it, `Err` on I/O failure.
@@ -53,9 +59,11 @@ impl SessionLock {
            Ok(mut file) => {
                write!(file, "{}", self.pid)?;
                file.sync_all()?;
+                tracing::debug!(path = %self.path.display(), pid = self.pid, "session lock acquired");
                return Ok(true);
            }
            Err(ref e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
+                tracing::debug!(path = %self.path.display(), "session lock already exists, checking staleness");
                // Lock file exists — check if it's stale.
            }
            Err(e) => return Err(e),
@@ -65,8 +73,10 @@ impl SessionLock {
        let content = fs::read_to_string(&self.path).unwrap_or_default();
        if let Ok(pid) = content.trim().parse::<u32>() {
            if Self::is_alive(pid) {
+                tracing::warn!(stale = pid, path = %self.path.display(), "session lock held by live process");
                return Ok(false);
            }
+            tracing::debug!(stale = pid, "stale lock detected, overwriting");
        }

        // Phase 3: stale lock — overwrite it atomically (best-effort).
@@ -94,21 +104,27 @@ impl SessionLock {
        let _ = fs::remove_file(&self.path);
    }

-    /// Check whether a process with the given PID is currently alive and
-    /// is actually a zesdex process (not a recycled PID from a different
-    /// program).
+    /// Check whether a process with the given PID is currently alive.
+    ///
+    /// Uses `kill(pid, 0)` on Unix via the `nix` or `libc` crate in production;
+    /// here we provide a best-effort check using the process table.
+    /// On non-Unix platforms this always returns `true` (conservative).
    fn is_alive(pid: u32) -> bool {
+        // On Unix, signal 0 checks process existence without sending a signal.
+        #[cfg(unix)]
+        {
            // SAFETY: `libc::kill(pid, 0)` does not send a signal; it only checks
-        // whether the process exists and the caller has permission to signal
-        // it. The integer argument is a PID already validated by `try_lock`.
-        if unsafe { libc::kill(pid as i32, 0) != 0 } {
+            // whether the process exists and the caller has permission to signal it.
+            // The integer argument is a PID validated by `try_lock`.
+            let pid_signed: i32 = match pid.try_into() {
+                Ok(p) => p,
+                Err(_) => return false,
+            };
+            if unsafe { libc::kill(pid_signed, 0) != 0 } {
                return false;
            }
            // Extra check: verify the PID belongs to a zesdex process via
-        // /proc/<pid>/exe to mitigate the PID-reuse race (a recycled PID
-        // from a different program would answer kill but shouldn't hold
-        // our lock). This is best-effort — /proc may not be available
-        // on all platforms.
+            // /proc/<pid>/exe to mitigate the PID-reuse race.
            let proc_exe = std::path::PathBuf::from(format!("/proc/{pid}/exe"));
            if let Ok(target) = std::fs::read_link(&proc_exe) {
                if let Ok(exe) = std::env::current_exe() {
@@ -119,6 +135,14 @@ impl SessionLock {
            }
            true
        }
+
+        #[cfg(not(unix))]
+        {
+            // Fallback: always assume alive (conservative).
+            let _ = pid;
+            true
+        }
+    }
 }

 impl Drop for SessionLock {
@@ -0,0 +1,127 @@
+//! Pure domain entity for application configuration.
+//!
+//! Defines `AppConfig`, `ProviderConfig`, and `ModelRole` — the data
+//! structures that describe which LLM providers are registered, which
+//! model roles exist, and which provider/model is the default.
+//!
+//! # Architecture
+//! These are pure data structures with **no I/O logic**. Load/save
+//! responsibilities live in `AppConfigRepository` (domain::repository).
+//!
+//! ## Data Flow
+//! 1. `AppConfig` is deserialised from `app_config.json` at startup
+//! 2. The HTTP handler layer calls `SettingsService::update_provider()`
+//!    to mutate the provider map
+//! 3. The modified `AppConfig` is serialised back to `app_config.json`
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+/// Top-level application configuration.
+///
+/// Holds the registry of configured LLM providers, named model roles
+/// (logical profiles mapping to a provider+model pair), and the default
+/// provider/model selection.
+///
+/// ## Fields
+/// - `providers` — map of provider name → connection details
+/// - `model_roles` — map of role name → provider/model/temperature
+/// - `default_provider` — the provider to use when none is specified
+/// - `default_model` — the model to use when none is specified
+/// - `default_context_window` — fallback context window size in tokens
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AppConfig {
+    pub providers: HashMap<String, ProviderConfig>,
+    pub model_roles: HashMap<String, ModelRole>,
+    pub default_provider: String,
+    pub default_model: String,
+    pub default_context_window: u32,
+}
+
+/// Connection details for a single LLM provider endpoint.
+///
+/// ## Fields
+/// - `api_base` — base URL for the provider API
+/// - `api_key_env` — optional environment variable name holding the API key
+/// - `default_model` — optional default model name for this provider
+/// - `default_api_key` — optional inline API key (less secure than env var)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProviderConfig {
+    pub api_base: String,
+    pub api_key_env: Option<String>,
+    pub default_model: Option<String>,
+    pub default_api_key: Option<String>,
+}
+
+/// A named model role mapping to a specific provider/model with parameters.
+///
+/// Roles allow the UI to present logical profiles (e.g. "fast", "reasoning")
+/// that abstract over concrete provider+model strings.
+///
+/// ## Fields
+/// - `provider` — which provider serves this role
+/// - `model` — which model to use for this role
+/// - `max_tokens` — optional maximum output token limit
+/// - `context_window` — optional context window override
+/// - `temperature` — optional generation temperature
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ModelRole {
+    pub provider: String,
+    pub model: String,
+    pub max_tokens: Option<u32>,
+    pub context_window: Option<u32>,
+    pub temperature: Option<f32>,
+}
+
+/// Returns the default AppConfig with built-in "zen" and "router" providers.
+impl Default for AppConfig {
+    /// Construct an AppConfig with the default "zen" and "router" providers.
+    ///
+    /// ## Defaults
+    /// - Zen provider: `deepseek-v4-flash-free` model
+    /// - Router provider: `claude-opus-4-8` model
+    /// - Default role: "default" → zen / deepseek-v4-flash-free, temp 0.7
+    /// - `default_context_window`: 256,000 tokens
+    fn default() -> Self {
+        let mut providers = HashMap::new();
+        providers.insert(
+            "zen".to_string(),
+            ProviderConfig {
+                api_base: "https://opencode.ai/zen/v1".to_string(),
+                api_key_env: Some("API_KEY".to_string()),
+                default_model: Some("deepseek-v4-flash-free".to_string()),
+                default_api_key: None,
+            },
+        );
+        providers.insert(
+            "router".to_string(),
+            ProviderConfig {
+                api_base: "https://9router.asepharyana.my.id/v1".to_string(),
+                api_key_env: Some("ROUTER_API_KEY".to_string()),
+                default_model: Some("claude-opus-4-8".to_string()),
+                default_api_key: None,
+            },
+        );
+
+        let mut model_roles = HashMap::new();
+        model_roles.insert(
+            "default".to_string(),
+            ModelRole {
+                provider: "zen".to_string(),
+                model: "deepseek-v4-flash-free".to_string(),
+                max_tokens: None,
+                context_window: None,
+                temperature: Some(0.7),
+            },
+        );
+
+        Self {
+            providers,
+            model_roles,
+            default_provider: "zen".to_string(),
+            default_model: "deepseek-v4-flash-free".to_string(),
+            default_context_window: 256_000,
+        }
+    }
+}
@@ -0,0 +1,157 @@
+//! Command types for CMS domain operations.
+//!
+//! Following the `NewXxx` / `XxxPatch` pattern from clean architecture,
+//! these types encapsulate the input data for create/update operations
+//! on domain entities. They decouple presentation DTOs from the entity
+//! mutation surface and provide a clear boundary for validation.
+
+use std::collections::HashMap;
+
+use super::settings::InternetMode;
+
+// ---------------------------------------------------------------------------
+// Settings
+// ---------------------------------------------------------------------------
+
+/// Partial update command for `Settings`.
+///
+/// Every field is `Option`al — only non-`None` fields are applied to the
+/// existing settings instance. Use `apply_to()` to merge into a `Settings`
+/// value.
+#[derive(Debug, Clone, Default)]
+pub struct SettingsPatch {
+    /// Override the internet access mode.
+    pub internet_mode: Option<String>,
+    /// Override the active provider name.
+    pub provider: Option<String>,
+    /// Override the active model name.
+    pub model: Option<String>,
+    /// Replace the entire API-keys map.
+    pub api_keys: Option<HashMap<String, String>>,
+    /// Override the max tokens for completions.
+    pub max_tokens: Option<Option<u32>>,
+    /// Override the temperature for completions.
+    pub temperature: Option<Option<f32>>,
+    /// Override the review max lessons per run.
+    pub review_max_lessons_per_run: Option<usize>,
+    /// Override the adaptive review max skip count.
+    pub adaptive_review_max_skip: Option<u32>,
+    /// Override the verify shell command.
+    pub verify_command: Option<Option<String>>,
+    /// Override the verify timeout in milliseconds.
+    pub verify_timeout_ms: Option<u64>,
+    /// Override the max concurrency for workflow execution.
+    pub workflow_max_concurrency: Option<usize>,
+    /// Override the review-enabled flag.
+    pub review_enabled: Option<bool>,
+    /// Override the session-archive-enabled flag.
+    pub session_archive_enabled: Option<bool>,
+    /// Override the LSP auto-provision flag.
+    pub lsp_auto_provision: Option<bool>,
+    /// Override the list of LSP-managed languages.
+    pub lsp_languages: Option<Vec<String>>,
+    /// Override the hive-mind node timeout in milliseconds.
+    pub hive_mind_node_timeout_ms: Option<u64>,
+}
+
+impl SettingsPatch {
+    /// Merge this patch into `settings`, overwriting each non-`None` field.
+    ///
+    /// Flow: for each optional field, if `Some`, assign it to the target.
+    ///
+    /// ## Errors
+    /// Returns `Err` with a message if `internet_mode` is set to an
+    /// unrecognised value.
+    pub fn apply_to(&self, settings: &mut super::settings::Settings) -> Result<(), String> {
+        if let Some(ref val) = self.internet_mode {
+            settings.internet_mode = match val.as_str() {
+                "Off" => InternetMode::Off,
+                "ReadOnly" => InternetMode::ReadOnly,
+                "Full" => InternetMode::Full,
+                _ => {
+                    return Err(format!(
+                        "invalid internet_mode '{val}'; expected Off, ReadOnly, or Full"
+                    ))
+                }
+            };
+        }
+        if let Some(ref val) = self.provider {
+            settings.provider = val.clone();
+        }
+        if let Some(ref val) = self.model {
+            settings.model = val.clone();
+        }
+        if let Some(ref val) = self.api_keys {
+            settings.api_keys = val.clone();
+        }
+        if let Some(val) = self.max_tokens {
+            settings.max_tokens = val;
+        }
+        if let Some(val) = self.temperature {
+            settings.temperature = val;
+        }
+        if let Some(val) = self.review_max_lessons_per_run {
+            settings.review_max_lessons_per_run = val;
+        }
+        if let Some(val) = self.adaptive_review_max_skip {
+            settings.adaptive_review_max_skip = val;
+        }
+        if let Some(ref val) = self.verify_command {
+            settings.verify_command = val.clone();
+        }
+        if let Some(val) = self.verify_timeout_ms {
+            settings.verify_timeout_ms = val;
+        }
+        if let Some(val) = self.workflow_max_concurrency {
+            settings.workflow_max_concurrency = val;
+        }
+        if let Some(val) = self.review_enabled {
+            settings.flags.review_enabled = val;
+        }
+        if let Some(val) = self.session_archive_enabled {
+            settings.flags.session_archive_enabled = val;
+        }
+        if let Some(val) = self.lsp_auto_provision {
+            settings.flags.lsp_auto_provision = val;
+        }
+        if let Some(ref val) = self.lsp_languages {
+            settings.lsp_languages = val.clone();
+        }
+        if let Some(val) = self.hive_mind_node_timeout_ms {
+            settings.hive_mind_node_timeout_ms = val;
+        }
+        Ok(())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Memory
+// ---------------------------------------------------------------------------
+
+/// Command to create a new memory entry.
+///
+/// All required fields are non-optional; optional fields use `Option`
+/// and default to sensible values (empty or the service default).
+#[derive(Debug, Clone)]
+pub struct NewMemory {
+    /// Unique name / slug for the memory.
+    pub name: String,
+    /// One-line summary of what the memory captures.
+    pub description: String,
+    /// The full memory content.
+    pub content: String,
+    /// Category kind (defaults to "reference" in the handler).
+    pub kind: Option<String>,
+    /// Outcome of the remembered action.
+    pub outcome: Option<String>,
+    /// Lifecycle stage (defaults to "new" in the handler).
+    pub lifecycle: Option<String>,
+    /// Scope context for the memory.
+    pub scope: Option<String>,
+    /// Code snippet captured before the action.
+    pub before_snippet: Option<String>,
+    /// Code snippet captured after the action.
+    pub after_snippet: Option<String>,
+    /// Source provenances (files, conversations, etc.).
+    pub provenances: Option<Vec<String>>,
+}
@@ -0,0 +1,15 @@
+//! Pure domain entity for conversations and chat messages.
+//!
+//! Re-exports the canonical `Conversation`, `ChatMessage`, and `Role`
+//! types from the core module to provide a consistent domain import
+//! boundary within the CMS module. All CMS code references conversation
+//! types through this module rather than depending on the core module
+//! directly.
+//!
+//! ## Re-exports
+//! - `Conversation` — top-level conversation container with message list
+//! - `ChatMessage` — a single message with role, content, and tool metadata
+//! - `Role` — message role enum (User, Assistant, System, Tool)
+
+pub use crate::core::message::{ChatMessage, Role};
+pub use crate::core::conversation::Conversation;
@@ -0,0 +1,81 @@
+//! Pure domain entity for the edit log — an append-only log of file mutations.
+//!
+//! Records every file mutation made by any tool, enabling audit trails
+//! and potential undo operations. Each entry captures the tool name,
+//! target path, reason, content hash, and byte delta.
+//!
+//! # Architecture
+//! This is a pure data structure with **no I/O logic**. Load/save
+//! responsibilities live in `EditLogRepository` (domain::repository).
+//!
+//! ## Data Flow
+//! 1. Tools call `EditLog::push()` to record each mutation
+//! 2. The in-memory `EditLog` is periodically flushed to disk by the repo
+//! 3. Oldest entries are evicted from the in-memory cache when
+//!    `MAX_MEMORY_ENTRIES` is exceeded (prevents unbounded growth)
+
+use serde::{Deserialize, Serialize};
+
+/// A single recorded file edit event.
+///
+/// ## Fields
+/// - `ts` — Unix timestamp (seconds) when the edit occurred
+/// - `tool` — name of the tool that performed the edit (e.g. "Bash", "Edit")
+/// - `path` — absolute file path that was modified
+/// - `reason` — human-readable explanation of why the edit was made
+/// - `content_sha256` — SHA-256 hex digest of the content *after* the edit
+/// - `bytes_delta` — signed byte count change (+added, -removed)
+/// - `origin` — origin identifier (which agent / session context)
+/// - `session_id` — session in which this edit was performed
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EditLogEntry {
+    pub ts: i64,
+    pub tool: String,
+    pub path: String,
+    pub reason: String,
+    pub content_sha256: String,
+    pub bytes_delta: i64,
+    pub origin: String,
+    pub session_id: String,
+}
+
+/// Maximum number of edit entries held in memory at once.
+///
+/// Beyond this limit, old entries are dropped from the in-memory cache
+/// to prevent unbounded memory growth in long-running sessions.
+pub const MAX_MEMORY_ENTRIES: usize = 10_000;
+
+/// In-memory view of a session's edit log.
+///
+/// Wraps a `Vec<EditLogEntry>` and provides basic query helpers.
+#[derive(Debug, Clone)]
+pub struct EditLog {
+    /// Ordered list of edit entries (newest appended last).
+    pub entries: Vec<EditLogEntry>,
+}
+
+impl EditLog {
+    /// Create an empty edit log with no entries.
+    pub fn new() -> Self {
+        Self {
+            entries: Vec::new(),
+        }
+    }
+
+    /// Return the number of in-memory entries.
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Return `true` if the log contains no entries.
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+}
+
+impl Default for EditLog {
+    /// Returns an empty `EditLog` via `EditLog::new()`.
+    fn default() -> Self {
+        Self::new()
+    }
+}
@@ -0,0 +1,51 @@
+//! Domain error types for the CMS module.
+//!
+//! Typed error enums for repository and service operations.
+//!
+//! # Components
+//!
+//! - [`RepositoryError`] — persistence-layer errors (not found, conflict, I/O)
+//! - [`ServiceError`] — use-case / orchestration errors (invalid input, generic)
+
+use std::fmt;
+
+use crate::error::DomainError;
+
+/// Shared repository error type for CMS persistence operations.
+pub type RepositoryError = DomainError;
+
+/// Errors from service / use-case operations in the CMS domain.
+#[derive(Debug)]
+pub enum ServiceError {
+    /// A repository operation failed.
+    Repository(DomainError),
+    /// The provided input is invalid.
+    InvalidInput(String),
+    /// A generic error with a message.
+    Other(String),
+}
+
+impl From<DomainError> for ServiceError {
+    fn from(err: DomainError) -> Self {
+        ServiceError::Repository(err)
+    }
+}
+
+impl fmt::Display for ServiceError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ServiceError::Repository(err) => write!(f, "repository error: {err}"),
+            ServiceError::InvalidInput(msg) => write!(f, "invalid input: {msg}"),
+            ServiceError::Other(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+impl std::error::Error for ServiceError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ServiceError::Repository(err) => Some(err),
+            _ => None,
+        }
+    }
+}
@@ -0,0 +1,109 @@
+//! Pure domain entity for long-term agent memory.
+//!
+//! A `Memory` entry stores a named, kinded piece of information (lesson,
+//! reference, fact) with frontmatter metadata and free-form markdown
+//! content. Memories are persisted as individual `.md` files with YAML
+//! frontmatter.
+//!
+//! # Architecture
+//! This is a pure data structure with **no I/O logic**. Load/save
+//! responsibilities live in `MemoryRepository` (domain::repository).
+//!
+//! ## Utility Functions
+//! - `slugify()` — converts a name string into a filesystem-safe slug
+//! - `path()` — computes the on-disk path for a given memory name
+//!
+//! Both are pure computations that take parameters and perform no I/O.
+
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+/// A single memory entry with frontmatter metadata and markdown content.
+///
+/// ## Fields
+/// - `name` — unique identifier / title for this memory
+/// - `description` — short summary of what this memory contains
+/// - `content` — free-form markdown body
+/// - `kind` — category/tag (e.g. "lesson", "reference", "fact")
+/// - `created_at` — Unix timestamp of creation
+/// - `updated_at` — Unix timestamp of last modification
+/// - `outcome` — optional outcome of applying this memory
+/// - `lifecycle` — lifecycle stage (e.g. "active", "archived")
+/// - `scope` — optional scope qualifier (which session/context this applies to)
+/// - `before_snippet` — optional context snapshot before memory was applied
+/// - `after_snippet` — optional context snapshot after memory was applied
+/// - `provenances` — list of origin identifiers that created or confirmed this memory
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Memory {
+    pub name: String,
+    pub description: String,
+    pub content: String,
+    pub kind: String,
+    pub created_at: i64,
+    pub updated_at: i64,
+    pub outcome: Option<String>,
+    pub lifecycle: String,
+    pub scope: Option<String>,
+    pub before_snippet: Option<String>,
+    pub after_snippet: Option<String>,
+    pub provenances: Vec<String>,
+}
+
+impl Memory {
+    /// Convert an arbitrary string into a filesystem-safe slug.
+    ///
+    /// Flow: lowercase → replace non-alphanumeric chars with `-` →
+    /// collapse/trim repeated `-`.
+    ///
+    /// Returns `None` if the result is empty or exceeds 80 characters.
+    pub fn slugify(s: &str) -> Option<String> {
+        // Phase 1: replace every non-alphanumeric character with '-'
+        let slug: String = s
+            .to_lowercase()
+            .chars()
+            .map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
+            .collect();
+        // Phase 2: collapse consecutive '-' separators
+        let slug: String = slug
+            .split('-')
+            .filter(|s| !s.is_empty())
+            .collect::<Vec<_>>()
+            .join("-");
+        if slug.is_empty() || slug.len() > 80 {
+            return None;
+        }
+        Some(slug)
+    }
+
+    /// Compute the on-disk path for a memory of the given name.
+    ///
+    /// ## Parameters
+    /// - `memory_dir` — the base directory for memory storage
+    /// - `name` — the memory name (will be slugified internally)
+    ///
+    /// Falls back to `"memory.md"` when the name slugifies to an empty
+    /// or invalid string.
+    ///
+    /// ## Pure Computation
+    /// This function performs **no I/O** — it only computes a path.
+    pub fn path(memory_dir: &Path, name: &str) -> PathBuf {
+        let slug = Self::slugify(name).unwrap_or_else(|| "memory".to_string());
+        let clean: String = format!("{slug}.md")
+            .chars()
+            .map(|c| {
+                if c.is_ascii_alphanumeric() || c == '.' || c == '-' {
+                    c
+                } else {
+                    '-'
+                }
+            })
+            .collect();
+        let clean = clean.trim_start_matches('.').to_string();
+        memory_dir.join(if clean.is_empty() {
+            "memory.md".to_string()
+        } else {
+            clean
+        })
+    }
+}
@@ -0,0 +1,52 @@
+//! Domain layer for CMS — pure entities, value objects, repository traits,
+//! and service interfaces.
+//!
+//! This is the innermost layer of the Clean Architecture onion. It has **zero
+//! infrastructure dependencies** — all I/O is expressed through repository
+//! traits defined in [`repository`], and business operations through service
+//! traits in [`service`].
+//!
+//! ## Sub-modules
+//! - `app_config` — provider configuration model (`AppConfig`, `ProviderConfig`, `ModelRole`)
+//! - `conversation` — conversation entity + chat message model (re-exported from core)
+//! - `edit_log` — edit log model (`EditLog`, `EditLogEntry`)
+//! - `memory` — memory file model (`Memory`)
+//! - `settings` — application settings model (`Settings`, `InternetMode`, `SettingsFlags`)
+//! - `repository` — trait definitions for all persistence adapters
+//! - `service` — trait definitions for all application services
+//!
+//! ## Key Design Principle
+//! Domain types are plain Rust structs with `serde` for serialisation.
+//! They contain no I/O, no framework imports, and no side effects.
+
+pub mod app_config;
+pub mod commands;
+pub mod conversation;
+pub mod edit_log;
+pub mod error;
+pub mod memory;
+pub mod repository;
+pub mod service;
+pub mod settings;
+
+pub use app_config::AppConfig;
+pub use app_config::ModelRole;
+pub use app_config::ProviderConfig;
+pub use conversation::Conversation;
+pub use edit_log::EditLog;
+pub use edit_log::EditLogEntry;
+pub use error::{RepositoryError, ServiceError};
+pub use memory::Memory;
+pub use repository::AppConfigRepository;
+pub use repository::ConversationRepository;
+pub use repository::EditLogRepository;
+pub use repository::MemoryRepository;
+pub use repository::RewindBlobRepository;
+pub use repository::SettingsRepository;
+pub use service::ConversationService;
+pub use service::MemoryService;
+pub use service::SettingsService;
+pub use commands::{NewMemory, SettingsPatch};
+pub use settings::InternetMode;
+pub use settings::Settings;
+pub use settings::SettingsFlags;
@@ -0,0 +1,126 @@
+//! Repository traits — pure abstraction boundaries for persistence.
+//!
+//! Each trait defines load / save / query operations that infrastructure
+//! adapters implement. The domain and application layers depend **only**
+//! on these traits, never on concrete persistence implementations.
+//!
+//! ## Traits
+//! - `SettingsRepository` — load/save `Settings` from/to a base directory
+//! - `AppConfigRepository` — load/save `AppConfig` from/to a base directory
+//! - `ConversationRepository` — load/save `Conversation` from/to a session directory
+//! - `MemoryRepository` — list/load/save/delete `Memory` entries
+//! - `RewindBlobRepository` — store/retrieve/list binary blobs per session
+//! - `EditLogRepository` — open/append/query edit log entries per session
+//!
+//! ## Dependency Inversion
+//! Application services accept these traits as generic type parameters,
+//! allowing the composition root to inject concrete implementations
+//! (file-based, SQLite-backed, etc.) without changing business logic.
+
+use std::path::Path;
+
+use super::app_config::AppConfig;
+use super::conversation::Conversation;
+use super::edit_log::{EditLog, EditLogEntry};
+use super::error::RepositoryError;
+use super::memory::Memory;
+use super::settings::Settings;
+
+/// Persistence contract for `Settings` (application settings model).
+///
+/// Implementors provide the actual I/O logic (e.g. file-based JSON storage).
+pub trait SettingsRepository {
+    /// Load `Settings` from the given base directory.
+    fn load(&self, base_dir: &Path) -> Result<Settings, RepositoryError>;
+
+    /// Persist `Settings` to the given base directory.
+    fn save(&self, base_dir: &Path, settings: &Settings) -> Result<(), RepositoryError>;
+}
+
+/// Persistence contract for `AppConfig` (provider and model configuration).
+///
+/// Implementors provide the actual I/O logic (e.g. file-based JSON storage).
+pub trait AppConfigRepository {
+    /// Load `AppConfig` from the given base directory.
+    fn load(&self, base_dir: &Path) -> Result<AppConfig, RepositoryError>;
+
+    /// Persist `AppConfig` to the given base directory.
+    fn save(&self, base_dir: &Path, config: &AppConfig) -> Result<(), RepositoryError>;
+}
+
+/// Persistence contract for `Conversation` (session conversation data).
+///
+/// Implementors provide the actual I/O logic (e.g. file-based JSON storage).
+pub trait ConversationRepository {
+    /// Load a `Conversation` from the given session directory.
+    fn load(&self, session_dir: &Path) -> Result<Conversation, RepositoryError>;
+
+    /// Persist a `Conversation` to the given session directory.
+    fn save(
+        &self,
+        session_dir: &Path,
+        conversation: &Conversation,
+    ) -> Result<(), RepositoryError>;
+}
+
+/// Persistence contract for `Memory` (long-term agent memory entries).
+///
+/// Implementors provide the actual I/O logic (e.g. per-memory markdown files).
+pub trait MemoryRepository {
+    /// List all memory slugs (filenames without extension) in the memory directory.
+    fn list(&self, memory_dir: &Path) -> Result<Vec<String>, RepositoryError>;
+
+    /// Load a single `Memory` by name from the memory directory.
+    fn load(&self, memory_dir: &Path, name: &str) -> Result<Memory, RepositoryError>;
+
+    /// Save (create or overwrite) a `Memory` in the memory directory.
+    fn save(&self, memory_dir: &Path, memory: &Memory) -> Result<(), RepositoryError>;
+
+    /// Delete a `Memory` by name from the memory directory.
+    fn delete(&self, memory_dir: &Path, name: &str) -> Result<(), RepositoryError>;
+}
+
+/// Persistence contract for rewind-snapshot binary blobs.
+///
+/// Blobs are keyed by an arbitrary caller-supplied key (e.g. a tool-call ID)
+/// within a session. They capture file snapshots for the "rewind" feature.
+pub trait RewindBlobRepository {
+    /// Store (or overwrite) a binary blob under `blob_key` for this session.
+    fn store_blob(
+        &self,
+        session_dir: &Path,
+        blob_key: &str,
+        data: &[u8],
+        mime_type: Option<&str>,
+    ) -> Result<(), RepositoryError>;
+
+    /// Retrieve a blob's raw bytes by key, or `None` if not found.
+    fn retrieve_blob(
+        &self,
+        session_dir: &Path,
+        blob_key: &str,
+    ) -> Result<Option<Vec<u8>>, RepositoryError>;
+
+    /// List all blob keys for this session, ordered oldest-first.
+    fn list_blob_keys(&self, session_dir: &Path) -> Result<Vec<String>, RepositoryError>;
+}
+
+/// Persistence contract for `EditLog` (append-only file mutation log).
+///
+/// Implementors manage an append-only log of `EditLogEntry` items per session,
+/// typically persisted to a file for audit and potential undo.
+pub trait EditLogRepository {
+    /// Open (or initialise) the edit log for a session directory.
+    fn open(&self, session_dir: &Path) -> Result<EditLog, RepositoryError>;
+
+    /// Append one entry to the log and persist immediately (write-through).
+    fn append(
+        &self,
+        session_dir: &Path,
+        log: &mut EditLog,
+        entry: EditLogEntry,
+    ) -> Result<(), RepositoryError>;
+
+    /// Return a cloned copy of all in-memory entries for inspection.
+    fn entries(&self, log: &EditLog) -> Vec<EditLogEntry>;
+}
@@ -0,0 +1,64 @@
+//! Service trait definitions — use-case boundaries for CMS operations.
+//!
+//! These traits define the public API of the application use-cases.
+//! They are implemented by concrete types in the `application` layer
+//! and consumed by infrastructure adapters (HTTP handlers, CLI commands).
+//!
+//! ## Traits
+//! - `SettingsService` — load/save settings, update provider config
+//! - `ConversationService` — load/save conversations, add messages
+//! - `MemoryService` — list/save/delete session memories
+//!
+//! ## Dependency Inversion
+//! Application service implementations accept repository traits as generic
+//! type parameters. Infrastructure adapters depend only on these service
+//! traits, never on concrete implementations.
+
+use super::conversation::{ChatMessage, Conversation};
+use super::error::ServiceError;
+use super::memory::Memory;
+use super::settings::Settings;
+
+/// Use-cases for application settings.
+pub trait SettingsService {
+    /// Load the current `Settings` from the default store location.
+    fn load_settings(&self) -> Result<Settings, ServiceError>;
+
+    /// Persist updated `Settings` to the default store location.
+    fn save_settings(&self, settings: &Settings) -> Result<(), ServiceError>;
+
+    /// Update (or insert) a provider configuration entry.
+    fn update_provider(
+        &self,
+        name: &str,
+        config: &super::app_config::ProviderConfig,
+    ) -> Result<(), ServiceError>;
+}
+
+/// Use-cases for conversation (session message) management.
+pub trait ConversationService {
+    /// Load a `Conversation` for the given session ID.
+    fn load_conversation(&self, session_id: &str) -> Result<Conversation, ServiceError>;
+
+    /// Persist a `Conversation` to its session storage.
+    fn save_conversation(&self, conv: &Conversation) -> Result<(), ServiceError>;
+
+    /// Append a single `ChatMessage` to the conversation and persist.
+    fn add_message(
+        &self,
+        conv: &mut Conversation,
+        msg: ChatMessage,
+    ) -> Result<(), ServiceError>;
+}
+
+/// Use-cases for long-term memory management.
+pub trait MemoryService {
+    /// List all memory slugs (filenames without extension).
+    fn list_memories(&self) -> Result<Vec<String>, ServiceError>;
+
+    /// Save (create or overwrite) a `Memory`.
+    fn save_memory(&self, memory: &Memory) -> Result<(), ServiceError>;
+
+    /// Delete a `Memory` by its slug/name.
+    fn delete_memory(&self, name: &str) -> Result<(), ServiceError>;
+}
@@ -0,0 +1,120 @@
+//! Pure domain entity for application settings.
+//!
+//! Defines `Settings` (top-level user configuration), `SettingsFlags`
+//! (grouped boolean toggles), and `InternetMode` (network access level).
+//! Serialised to `settings.json` by the infrastructure layer.
+//!
+//! # Architecture
+//! This is a pure data structure with **no I/O logic**. Load/save
+//! responsibilities live in `SettingsRepository` (domain::repository).
+//!
+//! ## Settings Fields
+//! - `internet_mode` — network access policy (Off / ReadOnly / Full)
+//! - `provider` / `model` — default LLM provider and model name
+//! - `api_keys` — per-provider API key overrides (name → key)
+//! - `max_tokens` / `temperature` — generation parameter defaults
+//! - `review_max_lessons_per_run` — max lessons per auto-review pass
+//! - `verify_command` — optional shell command to run for verification
+//! - `workflow_max_concurrency` — max parallel hive-mind nodes
+//! - `hive_mind_node_timeout_ms` — per-node timeout for hive-mind orchestration
+//! - `flags` — grouped boolean feature toggles
+//! - `lsp_languages` — list of language IDs for LSP auto-provisioning
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+/// Controls how much network access the agent is permitted during a session.
+///
+/// ## Variants
+/// - `Off` — no network access
+/// - `ReadOnly` — HTTP GET / HEAD only
+/// - `Full` — any HTTP method permitted
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub enum InternetMode {
+    /// No network access permitted.
+    #[default]
+    Off,
+    /// HTTP GET / HEAD requests only.
+    ReadOnly,
+    /// Any HTTP method permitted.
+    Full,
+}
+
+/// Grouped boolean feature toggles for the application.
+///
+/// Kept as a separate struct to avoid clippy's
+/// `default-too-many-fields` threshold on `Settings`.
+///
+/// ## Fields
+/// - `review_enabled` — enable automatic inline review after edits
+/// - `session_archive_enabled` — enable periodic session archiving
+/// - `lsp_auto_provision` — auto-provision LSP language servers on project open
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SettingsFlags {
+    pub review_enabled: bool,
+    pub session_archive_enabled: bool,
+    pub lsp_auto_provision: bool,
+}
+
+impl Default for SettingsFlags {
+    /// Returns the default flags with all features enabled.
+    fn default() -> Self {
+        Self {
+            review_enabled: true,
+            session_archive_enabled: true,
+            lsp_auto_provision: true,
+        }
+    }
+}
+
+/// Returns the default hive-mind node timeout (600 seconds).
+fn default_hive_mind_node_timeout_ms() -> u64 {
+    600_000
+}
+
+/// Top-level application settings model.
+///
+/// Serialised to `settings.json` by the infrastructure persistence layer.
+/// Holds LLM provider selection, generation parameters, feature flags,
+/// and workflow configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Settings {
+    pub internet_mode: InternetMode,
+    pub provider: String,
+    pub model: String,
+    pub api_keys: HashMap<String, String>,
+    pub max_tokens: Option<u32>,
+    pub temperature: Option<f32>,
+    pub review_max_lessons_per_run: usize,
+    pub adaptive_review_max_skip: u32,
+    pub verify_command: Option<String>,
+    pub verify_timeout_ms: u64,
+    pub workflow_max_concurrency: usize,
+    #[serde(flatten)]
+    pub flags: SettingsFlags,
+    pub lsp_languages: Vec<String>,
+    #[serde(default = "default_hive_mind_node_timeout_ms")]
+    pub hive_mind_node_timeout_ms: u64,
+}
+
+impl Default for Settings {
+    fn default() -> Self {
+        Self {
+            internet_mode: InternetMode::Off,
+            provider: "zen".to_string(),
+            model: "deepseek-v4-flash-free".to_string(),
+            api_keys: HashMap::new(),
+            max_tokens: None,
+            temperature: None,
+            review_max_lessons_per_run: 5,
+            adaptive_review_max_skip: 3,
+            verify_command: None,
+            verify_timeout_ms: 30_000,
+            workflow_max_concurrency: 5,
+            flags: SettingsFlags::default(),
+            lsp_languages: Vec::new(),
+            hive_mind_node_timeout_ms: 600_000,
+        }
+    }
+}
@@ -1,11 +1,17 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! In-memory conversation state: message history plus the system prompt and
 //! model parameters used to drive the LLM.
+//!
+//! # Flow
+//!
+//! [`Conversation::new`] → [`push`](Conversation::push) to add messages →
+//! [`to_api_messages`](Conversation::to_api_messages) to format for the LLM
+//! API (system prompt prepended).
+//!
+//! # Components
+//!
+//! - `Conversation` — message vector + session metadata + generation params
+//! - `push` / `rebuild_system` — mutation helpers
+//! - `to_api_messages` — formats messages for API consumption
 use serde::{Deserialize, Serialize};

 use super::message::{ChatMessage, Role};
@@ -13,11 +19,17 @@ use super::message::{ChatMessage, Role};
 /// A single conversation's message history and generation settings.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Conversation {
+    /// Ordered list of chat messages (user, assistant, tool, system).
    pub messages: Vec<ChatMessage>,
+    /// System prompt prepended at request time (see `to_api_messages`).
    pub system_prompt: String,
+    /// Foreign key referencing the owning session.
    pub session_id: String,
+    /// Model identifier string, e.g. `"anthropic/claude-opus-4-8"`.
    pub model: String,
+    /// Optional cap on output tokens.
    pub max_tokens: Option<u32>,
+    /// Optional temperature (0.0 – 2.0).
    pub temperature: Option<f32>,
 }

@@ -73,44 +85,4 @@ impl Conversation {
    pub fn is_empty(&self) -> bool {
        self.messages.is_empty()
    }
-
-    /// Persist the conversation to a JSON file at the given base directory.
-    ///
-    /// Flow: compute path from `session_id` → ensure directory exists →
-    /// serialize to pretty JSON → write-then-rename with fsync.
-    ///
-    /// Return: `Ok(())` on success, or an `io::Error` from any step.
-    pub fn save_conversation(&self, base_dir: &std::path::Path) -> std::io::Result<()> {
-        let dir = base_dir.join("sessions").join(&self.session_id);
-        std::fs::create_dir_all(&dir)?;
-        let path = dir.join("conversation.json");
-        let data = serde_json::to_string_pretty(self)?;
-        let tmp = dir.join("conversation.json.tmp");
-        std::fs::write(&tmp, data)?;
-        let f = std::fs::File::open(&tmp)?;
-        f.sync_all()?;
-        std::fs::rename(&tmp, path)?;
-        let _ = std::fs::File::open(&dir).and_then(|d| d.sync_all());
-        Ok(())
-    }
-
-    /// Load a conversation from a JSON file for the given session id.
-    ///
-    /// Flow: read `<base_dir>/sessions/<session_id>/conversation.json` →
-    /// JSON-parse.
-    ///
-    /// Return: the parsed `Conversation`, or an `io::Error` if the file is
-    /// missing or malformed.
-    pub fn load_conversation(
-        session_id: &str,
-        base_dir: &std::path::Path,
-    ) -> std::io::Result<Self> {
-        let path = base_dir
-            .join("sessions")
-            .join(session_id)
-            .join("conversation.json");
-        let data = std::fs::read_to_string(path)?;
-        let conv: Conversation = serde_json::from_str(&data)?;
-        Ok(conv)
-    }
 }
@@ -1,14 +1,20 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
-//! Chat message types shared across the entity layer: `Role` and `ChatMessage`
-//! with convenience constructors.
+//! Chat message types shared across the entity layer.
+//!
+//! Provides [`Role`] (conversation participant) and [`ChatMessage`] (a single
+//! message with optional tool-call metadata). Includes convenience constructors
+//! for each role: `user`, `assistant`, `system`, `tool`/`tool_result`.
+//!
+//! # Flow
+//!
+//! Messages are constructed via the typed constructors → pushed into
+//! [`Conversation`](super::conversation::Conversation) → serialized as JSON
+//! to `conversation.json`.
 use serde::{Deserialize, Serialize};

 /// The conversation participant who authored a message.
+///
+/// Variants: `User`, `Assistant`, `System`, `Tool`. Serialized as lowercase
+/// strings (e.g. `"user"`, `"assistant"`, `"system"`, `"tool"`).
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum Role {
    #[serde(rename = "user")]
@@ -43,12 +49,18 @@ impl std::fmt::Display for Role {
 /// chat-completion API structures.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatMessage {
+    /// Who sent this message (user, assistant, system, tool).
    pub role: Role,
+    /// The message text content. `None` for assistant messages that only
+    /// contain tool calls.
    pub content: Option<String>,
+    /// Tool-call requests attached to an assistant message (OpenAI-style).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<super::tool_call::ToolCall>>,
+    /// For tool-role messages: the `id` of the `ToolCall` being responded to.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_call_id: Option<String>,
+    /// Optional function name for the tool invocation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
 }
@@ -0,0 +1,35 @@
+//! Core domain entities shared across the Zesdex application.
+//!
+//! Contains pure data structures for conversations, messages, tool calls,
+//! usage statistics, provider API types, and store path configuration.
+//! All types derive `Serialize`/`Deserialize` for JSON persistence.
+//!
+//! # Sub-modules
+//!
+//! - [`conversation`] — Ordered conversation (vector of `ChatMessage`)
+//! - [`message`] — `ChatMessage` + `Role` enum
+//! - [`provider`] — LLM provider API types: `ChatRequest`, `ChatResponse`,
+//!   `StreamEvent`, `SseParser`, `ToolDef`, etc.
+//! - [`store`] — `Store` paths for data directories
+//! - [`tool_call`] — `ToolCall` + `ToolFunction` (function-calling request)
+//! - [`tool_result`] — `ToolCallResult` (function-calling response)
+//! - [`usage`] — `UsageStats` (token counts, costs)
+
+pub mod conversation;
+pub mod message;
+pub mod provider;
+pub mod store;
+pub mod tool_call;
+pub mod tool_result;
+pub mod usage;
+
+pub use conversation::Conversation;
+pub use message::{ChatMessage, Role};
+pub use provider::{
+    ChatRequest, ChatResponse, Choice, Delta, SseParser, StreamEvent, StreamOptions, TokenUsage,
+    ToolDef, ToolFunctionDef,
+};
+pub use store::Store;
+pub use tool_call::{ToolCall, ToolFunction};
+pub use tool_result::ToolCallResult;
+pub use usage::UsageStats;
@@ -1,13 +1,25 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! Provider-facing DTOs: chat completion request, response, streaming types,
 //! and the SSE stream parser.
+//!
+//! # Flow
+//!
+//! 1. **Request** — [`ChatRequest`] is built with model, messages, tools,
+//!    streaming options and sent to the LLM provider.
+//! 2. **Response** — Non-streaming responses arrive as [`ChatResponse`] with
+//!    [`Choice`]s containing the full [`ChatMessage`](super::message::ChatMessage).
+//! 3. **Streaming** — SSE chunks are fed into [`SseParser::feed`] which yields
+//!    [`StreamEvent`]s: token/text, reasoning, tool-call deltas, usage, done.
+//!
+//! # Components
+//!
+//! - `ChatRequest` / `StreamOptions` / `ToolDef` / `ToolFunctionDef` — outbound
+//! - `ChatResponse` / `Choice` / `Delta` / `TokenUsage` — non-streaming inbound
+//! - `StreamEvent` — one atomic streaming event (Token, Reasoning,
+//!   ToolCallDelta, Usage, Done, Error)
+//! - `SseParser` — incremental SSE frame parser: `feed()` → `Vec<StreamEvent>`
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
+use tracing;

 // ---------------------------------------------------------------------------
 // Chat request / response
@@ -17,23 +29,32 @@ use serde_json::Value;
 /// provider.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatRequest {
+    /// Model identifier, e.g. `"anthropic/claude-opus-4-8"`.
    pub model: String,
+    /// Full message history (system + user + assistant + tool turns).
    pub messages: Vec<super::message::ChatMessage>,
+    /// Maximum number of output tokens.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_tokens: Option<u32>,
+    /// Sampling temperature (0.0 – 2.0).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f32>,
+    /// Tool definitions available to the model.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tools: Option<Vec<ToolDef>>,
    /// Controls which (if any) function is called by the model.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_choice: Option<Value>,
+    /// Whether to use SSE streaming (`true`) or a single response.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream: Option<bool>,
+    /// Nucleus sampling threshold.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub top_p: Option<f32>,
+    /// Sequences where the model should stop generation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stop: Option<Vec<String>>,
+    /// Additional streaming options (e.g. `include_usage`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream_options: Option<StreamOptions>,
 }
@@ -48,38 +69,53 @@ pub struct StreamOptions {
 /// Wire format for a single tool definition sent to the provider.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolDef {
+    /// The tool type discriminator, e.g. `"function"`.
    #[serde(rename = "type")]
    pub type_: String,
+    /// The function definition (name, description, JSON schema).
    pub function: ToolFunctionDef,
 }

 /// Name, description, and JSON schema parameters for a tool definition.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolFunctionDef {
+    /// The function name the model may invoke.
    pub name: String,
+    /// Human-readable description of what the function does.
    pub description: String,
+    /// JSON Schema object describing the expected arguments.
    pub parameters: Value,
 }

 /// Non-streaming chat completion response returned by the provider.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ChatResponse {
+    /// Unique response identifier from the provider.
    pub id: String,
+    /// Object type, e.g. `"chat.completion"`.
    pub object: Option<String>,
+    /// Model identifier that produced this response.
    pub model: String,
+    /// One or more completion candidates.
    pub choices: Vec<Choice>,
+    /// Token usage statistics (prompt, completion, total).
    pub usage: Option<TokenUsage>,
+    /// Unix-timestamp of response creation.
    pub created: Option<i64>,
 }

 /// One completion candidate within a `ChatResponse.choices` list.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Choice {
+    /// Zero-based index of this choice in the candidate list.
    pub index: u32,
+    /// Full message (non-streaming response).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub message: Option<super::message::ChatMessage>,
+    /// Incremental delta (streaming response).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub delta: Option<Delta>,
+    /// Why the model stopped: `"stop"`, `"tool_calls"`, `"length"`, etc.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub finish_reason: Option<String>,
 }
@@ -87,10 +123,13 @@ pub struct Choice {
 /// Incremental delta emitted in a streaming SSE chunk.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Delta {
+    /// Role being set for the first streaming chunk.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub role: Option<super::message::Role>,
+    /// Incremental text content delta.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
+    /// Incremental tool-call delta (partial name/arguments).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<super::tool_call::ToolCall>>,
 }
@@ -98,11 +137,16 @@ pub struct Delta {
 /// Token counts and optional cost breakdown for a single completion request.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct TokenUsage {
+    /// Tokens consumed by the prompt (input).
    pub prompt_tokens: u32,
+    /// Tokens consumed by the completion (output).
    pub completion_tokens: u32,
+    /// Sum of prompt + completion tokens.
    pub total_tokens: u32,
+    /// Estimated cost for prompt tokens (provider-specific).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prompt_tokens_cost: Option<f64>,
+    /// Estimated cost for completion tokens (provider-specific).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub completion_tokens_cost: Option<f64>,
 }
@@ -114,28 +158,41 @@ pub struct TokenUsage {
 /// One atomic event extracted from an LLM streaming response stream.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum StreamEvent {
+    /// An incremental text token.
    Token(String),
+    /// An incremental reasoning token (Anthropic `reasoning_content`).
    Reasoning(String),
+    /// An incremental tool-call delta (partial ID, name, or arguments).
    ToolCallDelta {
+        /// Tool-call index (multiple calls in one response).
        index: usize,
+        /// Optional tool-call ID (usually in the first delta for a call).
        id: Option<String>,
+        /// Optional function name (usually in the first delta for a call).
        name: Option<String>,
+        /// Partial JSON arguments delta for this tool call.
        arguments_delta: String,
    },
+    /// Final usage chunk with token counts.
    Usage {
        prompt_tokens: u64,
        completion_tokens: u64,
        total_tokens: u64,
    },
+    /// Stream complete (all tokens have been delivered).
    Done,
+    /// A stream-level error occurred.
    Error(String),
 }

 /// Buffered SSE frame parser that accumulates raw `data:` lines and
 /// flushes a `StreamEvent` on each blank-line boundary.
 pub struct SseParser {
+    /// Leftover bytes from the last chunk that did not end with `\n`.
    buffer: String,
+    /// The current `event:` type (set by `event:` lines, cleared on flush).
    event_type: Option<String>,
+    /// Accumulated `data:` lines for the current event frame.
    data_lines: Vec<String>,
 }

@@ -273,7 +330,8 @@ impl SseParser {
                                                    );
                                                    0
                                                },
-                                            ) as usize;
+                                            );
+                                        let index = usize::try_from(index).unwrap_or(0);
                                        let id = tc
                                            .get("id")
                                            .and_then(|i| i.as_str())
@@ -1,12 +1,18 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! Filesystem layout for zesdex's persistent and scratch data directories.
+//!
+//! # Flow
+//!
+//! [`Store::new`] resolves all paths from OS data dir / temp dir →
+//! [`ensure_dirs`](Store::ensure_dirs) creates them on startup.
+//!
+//! # Components
+//!
+//! - `Store` — resolved path bundle (base, memory, scratch, images, downloads)
+//! - `new` — path computation (no I/O)
+//! - `ensure_dirs` — creates all directories if missing
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
+use tracing;

 /// Resolved paths for all data directories zesdex reads from and writes to.
 ///
@@ -14,10 +20,15 @@ use std::path::PathBuf;
 /// where memory, scratch, session images, and downloads live.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Store {
+    /// Top-level data directory, e.g. `~/.local/share/zesdex`.
    pub base_dir: PathBuf,
+    /// Temporary scratch root, usually under the OS temp dir.
    pub scratch_root: PathBuf,
+    /// Directory for persistent memory files (`.md` summaries).
    pub memory_dir: PathBuf,
+    /// Directory for per-session image snapshots.
    pub session_images_dir: PathBuf,
+    /// Directory for downloaded files.
    pub download_dir: PathBuf,
 }

@@ -29,9 +40,13 @@ impl Store {
    ///
    /// Why: paths are computed, not created — call `ensure_dirs` before use.
    pub fn new() -> Self {
-        let base = dirs::data_dir()
-            .unwrap_or_else(|| PathBuf::from(".local/share"))
-            .join("zesdex");
+        let base = if let Some(data_dir) = std::env::var("XDG_DATA_HOME").ok()
+            .or_else(|| std::env::var("HOME").ok().map(|h| format!("{h}/.local/share")))
+        {
+            PathBuf::from(data_dir).join("zesdex")
+        } else {
+            PathBuf::from(".local/share/zesdex")
+        };
        let scratch = std::env::temp_dir().join("zesdex-scratch");
        Store {
            memory_dir: base.join("memory"),
@@ -47,6 +62,7 @@ impl Store {
    ///
    /// Return: `Err` on the first directory that fails to create.
    pub fn ensure_dirs(&self) -> std::io::Result<()> {
+        tracing::debug!(base = %self.base_dir.display(), "ensuring store directories exist");
        std::fs::create_dir_all(&self.base_dir)?;
        std::fs::create_dir_all(&self.memory_dir)?;
        std::fs::create_dir_all(&self.scratch_root)?;
@@ -1,31 +1,42 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! Tool-call DTOs embedded in assistant chat messages.
 //!
-//! Flow: provider response/stream carries `tool_calls` on an assistant
-//! message → deserialized into `ToolCall`/`ToolFunction` → harness resolves
-//! `function.name` against `all_tools()` and runs it with
-//! `sanitize_tool_arguments(function.arguments)`.
+//! # Flow
+//!
+//! Provider response/stream carries `tool_calls` on an assistant message →
+//! deserialized into [`ToolCall`]/[`ToolFunction`] → harness resolves the
+//! function name against `all_tools()` and runs it after sanitizing arguments
+//! via [`sanitize_tool_arguments`] (which handles string-encoded JSON,
+//! control characters, and truncation).
+//!
+//! # Components
+//!
+//! - `ToolCall` — a single tool-invocation request (id + type + function)
+//! - `ToolFunction` — function name + raw arguments Value
+//! - `sanitize_tool_arguments` — normalizes argument shape, repairs truncation
+//! - `repair_json` — closes unclosed strings/braces/brackets in truncated JSON
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
+use tracing;

 /// A single tool-call request emitted by the model in an assistant message.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolCall {
+    /// Unique identifier for this tool call (referenced by `ToolCallResult`).
    pub id: String,
+    /// Discriminator, e.g. `"function"`.
    #[serde(rename = "type")]
    pub type_: String,
+    /// The function to invoke (name + arguments).
    pub function: ToolFunction,
 }

 /// The function name and raw arguments payload for a `ToolCall`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolFunction {
+    /// The function/tool name to dispatch against.
    pub name: String,
+    /// Arguments as a JSON Value (may be a string-encoded object before
+    /// `sanitize_tool_arguments` normalises it).
    pub arguments: Value,
 }

@@ -1,19 +1,29 @@
-#![allow(
-    clippy::cast_possible_truncation,
-    clippy::cast_sign_loss,
-    clippy::cast_precision_loss,
-    clippy::cast_possible_wrap
-)]
 //! Record of one completed tool invocation, kept for transcript/history.
+//!
+//! # Flow
+//!
+//! Tool harness completes execution → creates [`ToolCallResult`] with output,
+//! error flag, and wall-clock duration → appended to conversation history as
+//! a `Tool`-role [`ChatMessage`](super::message::ChatMessage).
+//!
+//! # Components
+//!
+//! - `ToolCallResult` — tool name + output + error flag + duration
+//! - `new` — convenience constructor
 use serde::{Deserialize, Serialize};

 /// Record of a completed tool invocation, kept for transcript/history.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ToolCallResult {
+    /// The `id` of the `ToolCall` this result responds to.
    pub tool_call_id: String,
+    /// The name of the tool that was invoked.
    pub tool_name: String,
+    /// The text output produced by the tool (or error message).
    pub output: String,
+    /// Whether the tool exited with an error.
    pub is_error: bool,
+    /// Wall-clock execution duration in milliseconds.
    pub duration_ms: u64,
 }

@@ -0,0 +1,40 @@
+//! Token usage accounting shared by streaming and non-streaming responses.
+//!
+//! # Flow
+//!
+//! Accumulated across all LLM API calls in a session. Each response updates
+//! the running totals; `last_*` fields capture the most recent call's values
+//! for interpolation display. Persisted alongside other session metadata.
+//!
+//! # Components
+//!
+//! - `UsageStats` — cumulative token/latency counters
+use serde::{Deserialize, Serialize};
+
+/// Cumulative token/latency counters for a session, persisted alongside it.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, Default)]
+pub struct UsageStats {
+    /// Total tokens consumed as input (prompt).
+    pub tokens_in: u64,
+    /// Total tokens generated as output (completion).
+    pub tokens_out: u64,
+    /// Most recent call's input tokens (for live interpolation display).
+    #[serde(default)]
+    pub last_tokens_in: u64,
+    /// Most recent call's output tokens (for live interpolation display).
+    #[serde(default)]
+    pub last_tokens_out: u64,
+    /// Total number of LLM API calls made this session.
+    pub api_calls: u64,
+    /// Tokens consumed by auto-review subagent calls.
+    pub review_tokens: u64,
+    /// Total wall-clock time spent on LLM API calls (milliseconds).
+    pub total_ms: u64,
+}
+
+impl UsageStats {
+    /// Create a new `UsageStats` with all counters zeroed.
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
@@ -0,0 +1,76 @@
+//! Shared domain error types for the entire domain layer.
+//!
+//! Provides [`DomainError`] — a unified repository-level error enum used
+//! by both the `auth` and `cms` modules (type-aliased as `RepositoryError`
+//! in each module). This avoids a dependency on `thiserror` while still
+//! giving callers distinct error variants to match on.
+//!
+//! # Flow
+//!
+//! Infrastructure adapters convert their native errors (I/O, serde, etc.)
+//! into `DomainError` via `From` impls. Domain service layers wrap
+//! `DomainError` in their own `ServiceError` enum via `From`.
+//!
+//! # Components
+//!
+//! - `DomainError` — 6 variants: `NotFound`, `Conflict`, `Io`, `Serde`,
+//!   `InvalidId`, `Other`
+//! - `From<std::io::Error>` — converts I/O errors
+//! - `From<serde_json::Error>` — converts serialisation errors
+
+use std::fmt;
+
+/// Unified repository-level error for domain operations.
+///
+/// Covers the common failure modes across all persistence adapters:
+/// missing entities, conflicts, I/O failures, serialization errors,
+/// invalid identifiers, and a catch-all `Other` variant.
+#[derive(Debug)]
+pub enum DomainError {
+    /// The requested entity was not found.
+    NotFound(String),
+    /// An operation failed due to a conflict (e.g. duplicate key).
+    Conflict(String),
+    /// An I/O error occurred during persistence.
+    Io(std::io::Error),
+    /// A serialization / deserialization error occurred.
+    Serde(String),
+    /// An identifier was rejected as invalid (e.g. path traversal).
+    InvalidId(String),
+    /// A generic / uncategorised error.
+    Other(String),
+}
+
+impl fmt::Display for DomainError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            DomainError::NotFound(msg) => write!(f, "not found: {msg}"),
+            DomainError::Conflict(msg) => write!(f, "conflict: {msg}"),
+            DomainError::Io(err) => write!(f, "I/O error: {err}"),
+            DomainError::Serde(msg) => write!(f, "serialization error: {msg}"),
+            DomainError::InvalidId(msg) => write!(f, "invalid id: {msg}"),
+            DomainError::Other(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+impl std::error::Error for DomainError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            DomainError::Io(err) => Some(err),
+            _ => None,
+        }
+    }
+}
+
+impl From<std::io::Error> for DomainError {
+    fn from(err: std::io::Error) -> Self {
+        DomainError::Io(err)
+    }
+}
+
+impl From<serde_json::Error> for DomainError {
+    fn from(err: serde_json::Error) -> Self {
+        DomainError::Serde(err.to_string())
+    }
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
semantic-release-bot	4ced6681c2	chore(release): 1.16.0 [skip ci] # [1.16.0](https://github.com/asepharyana/zesdex/compare/v1.15.2...v1.16.0) (2026-07-20) ### Features * tui: add usage overlay and sidebar for displaying usage statistics and tasks ([`da2ed6d`](https://github.com/asepharyana/zesdex/commit/da2ed6da25953b823354cc5deaa7b404b7b13cb0)) * tui: enhance agent turn with tool descriptions and sanitize arguments ([`08e2f99`](https://github.com/asepharyana/zesdex/commit/08e2f9998d3693e4cd57225491359c762d03f1d9)) * tui: implement agent turn engine for background processing and enhance input handling ([`792695b`](https://github.com/asepharyana/zesdex/commit/792695b65a393cfc54efe353480b7831e91544b5))	2026-07-20 04:33:19 +00:00
asepharyana	08e2f9998d	feat(tui): enhance agent turn with tool descriptions and sanitize arguments	2026-07-20 11:29:33 +07:00
asepharyana	792695b65a	feat(tui): implement agent turn engine for background processing and enhance input handling	2026-07-20 10:55:09 +07:00
asepharyana	da2ed6da25	feat(tui): add usage overlay and sidebar for displaying usage statistics and tasks feat(tui): implement status bar with connection and turn state indicators feat(tui): create workflow panel for agent status and progress visualization feat(web): introduce web frontend interface with static file serving feat(ws): add WebSocket interface for real-time communication and session management	2026-07-20 09:04:57 +07:00
asepharyana	bceba665c0	refactor: remove unused tracing imports across multiple files	2026-07-20 07:02:55 +07:00
asepharyana	714b4617dd	Refactor CMS and IAM modules: restructure presentation and command layers - Removed HTTP adapter module from CMS infrastructure. - Updated CMS infrastructure module to exclude HTTP. - Introduced presentation layer in CMS with DTOs and handlers for REST API. - Added command types for CMS domain operations to encapsulate input data. - Created typed error handling for CMS presentation layer. - Implemented handlers for CMS REST API endpoints. - Removed HTTP DTOs and handlers from IAM infrastructure. - Introduced command types for IAM domain operations. - Created presentation layer in IAM with DTOs and handlers for OAuth flow. - Implemented typed error handling for IAM presentation layer.	2026-07-20 06:53:01 +07:00
asepharyana	e9a8e93c83	Refactor session ID handling and improve error management - Introduced `SessionId` newtype for validated session identifiers, ensuring safety against path traversal attacks. - Updated session repository methods to accept `SessionId` instead of raw strings, enhancing type safety. - Removed redundant error handling in repository methods by leveraging the new `Error` type from `zesdex_utils`. - Simplified atomic JSON write operations by eliminating unnecessary error conversions. - Enhanced integer casting with a new `CastOr` trait for safer narrowing conversions. - Removed deprecated error handling code and consolidated error types across the codebase. - Updated HTTP handlers to utilize the new session ID validation, improving overall robustness.	2026-07-20 06:39:30 +07:00
asepharyana	ab1a54b72e	Refactor error handling in IAM and CMS crates - Introduced `RepositoryError` and `ServiceError` enums in both IAM and CMS domains for better error management. - Updated domain traits and services to return specific error types instead of `anyhow::Result`. - Enhanced session and OAuth repository implementations to handle errors more explicitly. - Refactored session service methods to return `Result<T, ServiceError>` for improved error handling. - Updated HTTP handlers to utilize the new error types. - Modified password hashing functions to run in a blocking context using `tokio::task::spawn_blocking`. - Added tests for new error handling mechanisms and async password functions.	2026-07-20 06:14:23 +07:00
asepharyana	5aaedbf787	docs: tambah doc comment, logging, dan inline comments di semua 255 file Meliputi: - File-level //! doc comment: tujuan file, alur kerja, komponen utama - Function-level /// doc comment: apa, parameter, return, flow, edge cases - Struct/enum/trait /// doc comment: peran, field docs - Tracing logging (tracing::info!/debug!/trace!/warn!/error!) di setiap fungsi - Inline comments untuk variable dan branching logic penting - Seluruh 8 crates di workspace: zesdex-backend, zesdex-cms, zesdex-entities, zesdex-iam, zesdex-infra, zesdex-ipc, zesdex-middleware, zesdex-utils - Build: 0 errors, 242/242 tests passed	2026-07-19 17:05:47 +07:00
semantic-release-bot	6680795ce7	chore(release): 1.15.2 [skip ci] ## [1.15.2](https://github.com/asepharyana/zesdex/compare/v1.15.1...v1.15.2) (2026-07-17) ### Bug Fixes * correct jitter range to ±25% and fix abort.rs doc — review findings ([`9b6e51d`](https://github.com/asepharyana/zesdex/commit/9b6e51dc677cc4b798532f1e63335785f2f7bbbf))	2026-07-17 20:21:33 +00:00
asepharyana	9b6e51dc67	fix: correct jitter range to ±25% and fix abort.rs doc — review findings	2026-07-18 03:18:27 +07:00
asepharyana	40524f930f	refactor: use mark_dirty() helper di input.rs, DRY 22 lokasi	2026-07-18 03:18:27 +07:00
asepharyana	086cb86f0d	refactor: extract is_aborted helpers, DRY 16 call sites	2026-07-18 03:18:27 +07:00
asepharyana	ff47bffe0c	refactor: reuse is_auth_error from provider.rs, DRY backend retry logic	2026-07-18 03:18:27 +07:00
asepharyana	431c8d3b89	refactor: unify 3 backoff implementations into shared helper	2026-07-18 03:18:27 +07:00
asepharyanaandClaude Opus 4.8	e32501ee59	refactor: extract session_id extraction helper, DRY auth.rs Extract duplicated session ID extraction + validation logic from SessionAuthMiddleware::call() and require_session() into two shared helper functions: extract_session_id and validate_and_build_identity. Removes ~60 lines of duplicated code while preserving behavior: - Both call sites now rely on the same extraction/validation path - User-Agent default remains empty string (existing behavior unchanged) - Error response format (401 with header/validation messages) unchanged Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 03:18:27 +07:00
asepharyanaandClaude Opus 4.8	7d8487cefb	refactor: consolidate #![allow(clippy::cast_*)] to crate roots Add the cast-allow block to zesdex-entities/src/lib.rs and zesdex-utils/src/lib.rs (which lacked it), then remove from 65 sub-files across all 8 crates. Build and all 223 tests continue to pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 03:18:27 +07:00
asepharyanaandClaude Opus 4.8	4cd38c9291	refactor: extract write_json_atomic helper, DRY 8 call sites Move the crash-safe write-then-rename pattern into zesdex-utils::write_json_atomic and apply it across: - zesdex-cms: app_config_repo, conversation_repo, settings_repo - zesdex-iam: oauth_repo, session_repo - zesdex-entities: Conversation::save_conversation, Session::save Excluded (non-JSON format): - rewind_blob_repo (binary blob) - memory_repo (markdown + frontmatter, not JSON) - session_lock (PID string, not JSON) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 03:18:27 +07:00
asepharyanaandClaude Opus 4.8	9a6ab62562	refactor: DRY cleanup — extract shared helpers, remove duplication across tools, LSP, overlays, and runtime Eliminate ~500 lines of duplicate code across 31 files by extracting shared functions, helpers, and consolidating repeated patterns. Highlights: - Toast helpers (toast_info/success/warning/error) on AppStateRest - push_event() helper for turn-event queue (19 callers consolidated) - log_write_edit_tool() shared fn (turn.rs + engine.rs ~50 lines saved) - resolve_api_key() shared fn (spawn.rs + provider.rs) - LSP call_positional() helper on LspClient - lsp_cursor_params() shared schema for 4 tool files -overlay_block() helper for consistent overlay title/border styling - cycle_selected_index(), path_not_found/a_directory() helpers - mark_dirty(), save_settings() on AppStateRest - Remove redundant Err(e) => Err(e) arms in LSP tools - Consolidate generate_workspace_tree (turn.rs → workspace.rs) - Simplify background-review wrapper args in auto/mod.rs Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-18 03:18:27 +07:00
asepharyana	b02754acd2	refactor: implement retry logic with exponential backoff and jitter for subagent and provider calls	2026-07-18 03:18:27 +07:00