chore(release): 1.18.1 [skip ci]

## [1.18.1](https://github.com/asepharyana/zesdex/compare/v1.18.0...v1.18.1) (2026-08-01) ### Bug Fixes * **nix:** restrict flake to x86_64-linux (nixpkgs 26.11 dropped darwin) ([0e0fd5d](https://github.com/asepharyana/zesdex/commit/0e0fd5df05e53a6fa17d481825f1a8c567214d0e))
fix(nix): restrict flake to x86_64-linux (nixpkgs 26.11 dropped darwin)
2026-08-01 11:15:52 +00:00 · 2026-08-01 18:03:50 +07:00 · 2026-08-01 17:58:44 +07:00 · 2026-07-22 16:17:18 +07:00 · 2026-07-22 07:33:49 +00:00 · 2026-07-22 14:29:50 +07:00
22 changed files with 1880 additions and 555 deletions
@@ -0,0 +1,20 @@
+name: Publish to FlakeHub
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  flakehub-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: DeterminateSystems/determinate-nix-action@main
+      - uses: DeterminateSystems/flakehub-push@main
+        with:
+          visibility: public
+          rolling: true
@@ -1,19 +1,35 @@
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
+## [1.18.1](https://github.com/asepharyana/zesdex/compare/v1.18.0...v1.18.1) (2026-08-01)
+
+
+### Bug Fixes
+
+* **nix:** restrict flake to x86_64-linux (nixpkgs 26.11 dropped darwin) ([0e0fd5d](https://github.com/asepharyana/zesdex/commit/0e0fd5df05e53a6fa17d481825f1a8c567214d0e))
+
+# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-22)


 ### Bug Fixes

 * add .releaserc.json for semantic-release configuration ([047d718](https://github.com/asepharyana/zesdex/commit/047d7183d72adaa0dd1a18a7f92b22d67d5aa85f))
+* **clippy:** replace type annotation with type alias + .insert() to avoid trivial_cast ([ffefa8c](https://github.com/asepharyana/zesdex/commit/ffefa8c07facbba83778f426ca4715569556b08a))
+* **rust:** remove unused imports, variables, and dead code causing CI build failures ([eb8cc17](https://github.com/asepharyana/zesdex/commit/eb8cc1799359a5ef5b4a4ee3a4202b87e80bfe6c))
+* **rust:** resolve all clippy warnings treated as errors in CI ([6b90c7e](https://github.com/asepharyana/zesdex/commit/6b90c7eb0d17d9281a377454e76dcc88a4232bc7))
+* **tui:** resolve remaining clippy errors in workspace ([eed4025](https://github.com/asepharyana/zesdex/commit/eed4025918de65eb2f3fd98cd3350d62f3322132))


 ### Features

 * add semantic search tool for code symbol indexing and searching ([fef3c92](https://github.com/asepharyana/zesdex/commit/fef3c925cd02e1d76e2d990cc6fa4e4cba64fab0))
+* Add SOLID principles and TDD reference documentation ([55677dd](https://github.com/asepharyana/zesdex/commit/55677dd67100813a5ed2b0bbf02257b57875ea07))
 * add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
 * **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
 * **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
+* **best_practice:** add code quality scanning and commit message validation ([8ecc588](https://github.com/asepharyana/zesdex/commit/8ecc588a3e125dc6a4b2e7eb4c12c6b344449c07))
+* centralize default constants and refactor overlay enter handling in TUI ([d615090](https://github.com/asepharyana/zesdex/commit/d615090dcd34bdb93be22c1c7ce4ba674363c258))
 * enhance context gathering in auto-review engine and agent runner ([dcc8c3e](https://github.com/asepharyana/zesdex/commit/dcc8c3ee42ef568843e04143048d799bc0882288))
+* enhance explore phase with TUI workflow event handling ([b3a4d13](https://github.com/asepharyana/zesdex/commit/b3a4d131d13d94bd307720cb50c2d02dedf92873))
 * implement Component trait for modular UI components and refactor TUI views to use it ([d59713d](https://github.com/asepharyana/zesdex/commit/d59713d3e3aa4325f9753bbddd068654e442f6ef))
+* implement mandatory explore phase with parallel subagents ([f368f3a](https://github.com/asepharyana/zesdex/commit/f368f3a1c0d2df02eb50542a81bcff96d9cdc420))
 * **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
 * **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
 * **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
@@ -26,211 +42,10 @@
 * **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
 * **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
 * **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
+* **tui:** introduce comprehensive state management for TUI interface ([8c58faf](https://github.com/asepharyana/zesdex/commit/8c58faf2920b7341dd50ace15044ff113cefb576))
 * **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
 * **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))

-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Bug Fixes
-
-* add .releaserc.json for semantic-release configuration ([047d718](https://github.com/asepharyana/zesdex/commit/047d7183d72adaa0dd1a18a7f92b22d67d5aa85f))
-
-
-### Features
-
-* add semantic search tool for code symbol indexing and searching ([fef3c92](https://github.com/asepharyana/zesdex/commit/fef3c925cd02e1d76e2d990cc6fa4e4cba64fab0))
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
-* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
-* enhance context gathering in auto-review engine and agent runner ([dcc8c3e](https://github.com/asepharyana/zesdex/commit/dcc8c3ee42ef568843e04143048d799bc0882288))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* refactor auto-review engine to use spawn_subagent for improved thread handling ([094eb4b](https://github.com/asepharyana/zesdex/commit/094eb4b8baa5abd878dcf5b611cf615955bc79eb))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add semantic search tool for code symbol indexing and searching ([fef3c92](https://github.com/asepharyana/zesdex/commit/fef3c925cd02e1d76e2d990cc6fa4e4cba64fab0))
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
-* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
-* enhance context gathering in auto-review engine and agent runner ([dcc8c3e](https://github.com/asepharyana/zesdex/commit/dcc8c3ee42ef568843e04143048d799bc0882288))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* refactor auto-review engine to use spawn_subagent for improved thread handling ([094eb4b](https://github.com/asepharyana/zesdex/commit/094eb4b8baa5abd878dcf5b611cf615955bc79eb))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add semantic search tool for code symbol indexing and searching ([fef3c92](https://github.com/asepharyana/zesdex/commit/fef3c925cd02e1d76e2d990cc6fa4e4cba64fab0))
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
-* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* refactor auto-review engine to use spawn_subagent for improved thread handling ([094eb4b](https://github.com/asepharyana/zesdex/commit/094eb4b8baa5abd878dcf5b611cf615955bc79eb))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add semantic search tool for code symbol indexing and searching ([fef3c92](https://github.com/asepharyana/zesdex/commit/fef3c925cd02e1d76e2d990cc6fa4e4cba64fab0))
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
-* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
-* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
-* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
-* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
-* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
-* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
-* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
-* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
-
-# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-20)
-
-
-### Features
-
-* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
-* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))

 # [1.17.0](https://github.com/asepharyana/zesdex/compare/v1.16.1...v1.17.0) (2026-07-20)

@@ -15,7 +15,7 @@ members = [
 ]

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

@@ -0,0 +1,57 @@
+//! Mandatory explore phase — spawns parallel subagents to discover context
+//! before the main agent begins its turn.
+//!
+//! # Flow
+//!
+//! Before the main agent's LLM loop, [`ExploreService::explore`] dispatches
+//! at least 3 subagents in parallel (code-structure scan, symbol-index query,
+//! semantic-context search). Their findings are consolidated into a single
+//! system message that is prepended to the conversation.
+//!
+//! # Why mandatory
+//!
+//! Without structured exploration the main agent works from an empty context
+//! window. The explore phase guarantees that every turn starts with a compact
+//! snapshot of what the codebase contains and where relevant code lives.
+
+use anyhow::Result;
+use std::collections::VecDeque;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+use zesdex_domain::agent::TurnEvent;
+
+/// The consolidated output of an explore phase — a set of system-level
+/// context messages injected before the main agent prompt.
+#[derive(Debug, Clone)]
+pub struct ExploreOutput {
+    /// One or more system messages summarising what the explore subagents
+    /// discovered. Prepended to the conversation by the turn service.
+    pub context_messages: Vec<String>,
+    /// Short human-readable summary of what was explored.
+    pub summary: String,
+}
+
+/// Service trait for the mandatory pre-turn exploration phase.
+///
+/// Implementors spawn ≥3 parallel subagents, each analysing a different
+/// aspect of the workspace, and return a consolidated summary.
+///
+/// # Object safety
+///
+/// This trait is `dyn`-safe — it returns `Pin<Box<dyn Future>>` so it can
+/// be stored as `Arc<dyn ExploreService>`.
+pub trait ExploreService: Send + Sync {
+    /// Run the explore phase.
+    ///
+    /// `query` — the user's current input phrase.
+    /// `workspace_root` — absolute path to the workspace root.
+    /// `turn_events` — shared event queue for TUI updates.
+    /// Returns structured context messages and a summary blob.
+    fn explore<'a>(
+        &'a self,
+        query: &'a str,
+        workspace_root: &'a str,
+        turn_events: &'a Arc<Mutex<VecDeque<TurnEvent>>>,
+    ) -> Pin<Box<dyn Future<Output = Result<ExploreOutput>> + Send + 'a>>;
+}
@@ -22,4 +22,8 @@ pub trait AgentTurnService: Send + Sync {
    ) -> impl Future<Output = Result<()>> + Send;
 }

+pub mod explore;
 pub mod turn_service;
+
+pub use explore::{ExploreOutput, ExploreService};
+pub use turn_service::{compact_messages_with_ai, AgentTurnServiceImpl};
@@ -8,7 +8,7 @@ use zesdex_domain::core::{ChatMessage, StreamEvent, ToolDef};
 use zesdex_domain::main_agent_prompt;

 use crate::ports::ProviderService;
-use super::ToolExecutor;
+use super::{ExploreService, ToolExecutor};

 /// Maximum tool-call iterations per agent turn before forcing termination.
 const MAX_TURN_ITERATIONS: u32 = 50;
@@ -107,21 +107,45 @@ fn emit_usage(turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>, usage: Option<(u64,
 // ---------------------------------------------------------------------------

 /// Service implementation for executing an agent turn asynchronously.
+///
+/// # Explore phase
+///
+/// Before the main LLM loop begins, [`AgentTurnServiceImpl`] runs a mandatory
+/// explore phase that spawns ≥3 parallel subagents (code structure, symbol
+/// index, semantic context) and injects their consolidated findings as a
+/// system message. See [`ExploreService`] for the trait contract.
 pub struct AgentTurnServiceImpl<P: ProviderService, T: ToolExecutor> {
    provider: Arc<P>,
    tool_executor: Arc<T>,
    tool_defs: Vec<ToolDef>,
+    /// Optional explore-phase service. When `Some`, the explore phase runs
+    /// before every turn; when `None` it is skipped (tests, daemon mode).
+    explore_service: Option<Arc<dyn ExploreService>>,
 }

 impl<P: ProviderService, T: ToolExecutor> AgentTurnServiceImpl<P, T> {
-    pub fn new(provider: Arc<P>, tool_executor: Arc<T>, tool_defs: Vec<ToolDef>) -> Self {
+    pub fn new(
+        provider: Arc<P>,
+        tool_executor: Arc<T>,
+        tool_defs: Vec<ToolDef>,
+    ) -> Self {
        Self {
            provider,
            tool_executor,
            tool_defs,
+            explore_service: None,
        }
    }

+    /// Attach an optional explore-phase service.
+    ///
+    /// When set, every call to `run_turn` will first run the explore phase
+    /// and inject the consolidated context as a system message.
+    pub fn with_explore(mut self, service: Arc<dyn ExploreService>) -> Self {
+        self.explore_service = Some(service);
+        self
+    }
+
    /// Execute a single LLM call with the current message list, handling
    /// streaming events and error reporting.
    async fn call_llm(
@@ -153,6 +177,61 @@ impl<P: ProviderService, T: ToolExecutor> super::AgentTurnService for AgentTurnS
            params.model
        );

+        // ── Phase 0: Mandatory explore ──────────────────────────────────
+        // Spawn ≥3 parallel subagents to discover code structure, symbols,
+        // and semantic context. The consolidated summary is injected as a
+        // system message before the main agent prompt.
+        if let Some(ref explorer) = self.explore_service {
+            // Determine workspace root from the first message's context or
+            // the first workspace root in params.
+            let user_query = params
+                .messages
+                .last()
+                .map(|m| m.content.clone().unwrap_or_default())
+                .unwrap_or_default();
+            let workspace_root = params
+                .workspace_roots
+                .first()
+                .map(|p| p.to_string_lossy().to_string())
+                .unwrap_or_else(|| ".".to_string());
+
+            push_event(
+                &params.turn_events,
+                TurnEvent::SystemNote {
+                    kind: "info".into(),
+                    message: "🔍 Exploring codebase structure...".into(),
+                },
+            );
+
+            match explorer.explore(&user_query, &workspace_root, &params.turn_events).await {
+                Ok(output) => {
+                    // Insert each context message as a system message.
+                    // They go at index 0 and are removed after the turn
+                    // like the main agent prompt.
+                    for ctx_msg in &output.context_messages {
+                        params
+                            .messages
+                            .insert(0, ChatMessage::system(ctx_msg.clone()));
+                    }
+                    info!(
+                        "Explore phase complete: {} context messages, {}",
+                        output.context_messages.len(),
+                        output.summary
+                    );
+                }
+                Err(e) => {
+                    warn!("Explore phase failed (non-fatal): {e}");
+                    push_event(
+                        &params.turn_events,
+                        TurnEvent::SystemNote {
+                            kind: "warn".into(),
+                            message: format!("Explore phase failed: {e}"),
+                        },
+                    );
+                }
+            }
+        }
+
        // Insert system prompt at position 0 once and keep it there for the
        // entire turn, avoiding per-iteration clones of the full message list.
        // It is removed before emitting the Compacted event so persistence
@@ -51,4 +51,7 @@ pub use cms::{
    settings_service::SettingsServiceImpl,
 };

-pub use agent::{AgentTurnService, ToolExecutor, turn_service::{AgentTurnServiceImpl, compact_messages_with_ai}};
+pub use agent::{
+    AgentTurnService, ExploreOutput, ExploreService, ToolExecutor,
+    turn_service::{AgentTurnServiceImpl, compact_messages_with_ai},
+};
@@ -181,7 +181,7 @@ fn scan_file(
        if trimmed.starts_with("use ") {
            for &forbidden in forbidden {
                let pattern = format!("use {forbidden}");
-                if trimmed.starts_with(&pattern) || trimmed.starts_with(&format!("use crate::")) {
+                if trimmed.starts_with(&pattern) || trimmed.starts_with("use crate::") {
                    // `use crate::` in domain could reference domain-only items — skip.
                    continue;
                }
@@ -234,11 +234,11 @@ pub fn audit_layering(root: &Path) -> Result<AuditReport> {
    let mut files_scanned = 0;

    for entry in Walk::new(&apps_dir).flatten() {
-        if entry.file_type().map_or(true, |ft| !ft.is_file()) {
+        if entry.file_type().is_none_or(|ft| !ft.is_file()) {
            continue;
        }
        let path = entry.path();
-        if path.extension().map_or(true, |e| e != "rs") {
+        if path.extension().is_none_or(|e| e != "rs") {
            continue;
        }

@@ -146,29 +146,29 @@ pub fn scan_quality_file(file_path: &Path, root: &Path) -> Vec<Finding> {
        }

        // ── Rule: Missing doc comments on pub items ────────────────────
-        if trimmed.starts_with("pub ") || trimmed.starts_with("pub(") {
-            if !prev_line_doc && !prev_line_empty {
-                // Check it's a struct/enum/fn/trait/type/const/mod
-                let is_item = trimmed.starts_with("pub fn ")
-                    || trimmed.starts_with("pub struct ")
-                    || trimmed.starts_with("pub enum ")
-                    || trimmed.starts_with("pub trait ")
-                    || trimmed.starts_with("pub type ")
-                    || trimmed.starts_with("pub const ")
-                    || trimmed.starts_with("pub mod ")
-                    || trimmed.starts_with("pub(crate) fn ")
-                    || trimmed.starts_with("pub(crate) struct ")
-                    || trimmed.starts_with("pub(crate) enum ")
-                    || trimmed.starts_with("pub(crate) trait ");
-                if is_item {
-                    findings.push(Finding {
-                        severity: super::arch_audit::Severity::Info,
-                        rule: "missing-doc",
-                        file: relative.clone(),
-                        line: line_num,
-                        message: format!("Missing doc comment on pub item: {trimmed}"),
-                    });
-                }
+        if (trimmed.starts_with("pub ") || trimmed.starts_with("pub("))
+            && !prev_line_doc && !prev_line_empty
+        {
+            // Check it's a struct/enum/fn/trait/type/const/mod
+            let is_item = trimmed.starts_with("pub fn ")
+                || trimmed.starts_with("pub struct ")
+                || trimmed.starts_with("pub enum ")
+                || trimmed.starts_with("pub trait ")
+                || trimmed.starts_with("pub type ")
+                || trimmed.starts_with("pub const ")
+                || trimmed.starts_with("pub mod ")
+                || trimmed.starts_with("pub(crate) fn ")
+                || trimmed.starts_with("pub(crate) struct ")
+                || trimmed.starts_with("pub(crate) enum ")
+                || trimmed.starts_with("pub(crate) trait ");
+            if is_item {
+                findings.push(Finding {
+                    severity: super::arch_audit::Severity::Info,
+                    rule: "missing-doc",
+                    file: relative.clone(),
+                    line: line_num,
+                    message: format!("Missing doc comment on pub item: {trimmed}"),
+                });
            }
        }

@@ -217,11 +217,11 @@ pub fn scan_quality(root: &Path) -> Result<CodeQualityReport> {
    let mut files_scanned = 0;

    for entry in Walk::new(&apps_dir).flatten() {
-        if entry.file_type().map_or(true, |ft| !ft.is_file()) {
+        if entry.file_type().is_none_or(|ft| !ft.is_file()) {
            continue;
        }
        let path = entry.path();
-        if path.extension().map_or(true, |e| e != "rs") {
+        if path.extension().is_none_or(|e| e != "rs") {
            continue;
        }
        files_scanned += 1;
@@ -108,13 +108,11 @@ pub fn validate_commit_message(msg: &str) -> Result<(), Vec<String>> {
            // Type-specific rules.
            match type_ {
                "chore" | "docs" | "refactor" | "test" | "style" | "perf" | "ci" | "build"
-                | "revert" => {
-                    if scope.is_some() {
-                        errors.push(format!(
-                            "'{type_}' commits should not use a scope. \
-                             Only 'feat' and 'fix' require scopes."
-                        ));
-                    }
+                | "revert" if scope.is_some() => {
+                    errors.push(format!(
+                        "'{type_}' commits should not use a scope. \
+                         Only 'feat' and 'fix' require scopes."
+                    ));
                }
                _ => {}
            }
@@ -0,0 +1,298 @@
+//! Mandatory explore phase — spawns ≥3 parallel subagents to discover
+//! codebase context before every agent turn, visible in the TUI workflow tab.
+//!
+//! # Flow
+//!
+//! `ExploreServiceImpl::explore()` →
+//!
+//! 1. Push `WorkflowAgentUpdate { Pending }` for each agent onto the turn-event
+//!    queue so the TUI workflow tab shows all 3.
+//! 2. Spawn **Code Structure** subagent (thread + tokio runtime).
+//! 3. Spawn **Symbol Index** subagent (thread + tokio runtime).
+//! 4. Spawn **Semantic Context** subagent (thread + tokio runtime).
+//! 5. Join all handles via `spawn_blocking`.
+//! 6. Push `Completed` / `Failed` events for each agent.
+//! 7. Consolidate findings into a system message → return.
+
+use crate::subagent::context::SubagentContext;
+use crate::subagent::division::AccessTier;
+use crate::subagent::engine::run_agent;
+use crate::tools::ToolCtx;
+use anyhow::{Context, Result};
+use std::collections::VecDeque;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+use std::thread;
+use tracing::{info, warn};
+use zesdex_application::agent::{ExploreOutput, ExploreService};
+use zesdex_domain::agent::{AgentStatus, TurnEvent};
+
+/// Number of parallel explore subagents.
+const EXPLORE_AGENT_COUNT: usize = 3;
+
+/// IDs for each explore agent (shown in the workflow tab).
+const EXPLORE_IDS: [&str; 3] = ["explore-structure", "explore-symbols", "explore-context"];
+
+/// Display names for the TUI workflow tab.
+const EXPLORE_LABELS: [&str; 3] = [
+    "📁 Code Structure",
+    "🔣 Symbol Index",
+    "🔍 Semantic Context",
+];
+
+/// Directives for each explore subagent.
+const EXPLORE_DIRECTIVES: [&str; 3] = [
+    // Agent 0: Code Structure
+    "You are a codebase structure explorer.\n\
+     1. List all top-level directories and files in the workspace root.\n\
+     2. Read Cargo.toml, package.json, or pyproject.toml at the root.\n\
+     3. List the apps/ or src/ directory contents.\n\
+     4. Identify main entry points (main.rs, main.py, index.ts, etc.).\n\
+     5. Count files by extension type.\n\
+     Use the ls_dir, read, grep, and glob tools. Be concise.",
+
+    // Agent 1: Symbol Index
+    "You are a symbol index explorer.\n\
+     1. Call the 'rebuild_index' tool to rebuild the symbol index.\n\
+     2. Call the 'list_symbols' tool with max_results: 100.\n\
+     3. Identify public APIs, entry points, and key types.\n\
+     4. Group symbols by language and kind.\n\
+     Be concise. Report what symbols exist and where they live.",
+
+    // Agent 2: Semantic Context
+    "You are a semantic context explorer.\n\
+     1. Call the 'rebuild_index' tool to ensure the index is fresh.\n\
+     2. Search for symbols related to the user's query using semantic_search.\n\
+     3. Search for config files, env variables, and settings.\n\
+     4. Search for test files and test patterns.\n\
+     Be concise. Report relevant code areas for the task.\n\
+     Use the semantic_search, grep, glob, and read tools.",
+];
+
+// ---------------------------------------------------------------------------
+//  Credentials
+// ---------------------------------------------------------------------------
+
+/// LLM credentials for explore subagents.
+pub struct Credentials {
+    pub base_url: String,
+    pub api_key: String,
+    pub model: String,
+}
+
+// ---------------------------------------------------------------------------
+//  ExploreServiceImpl — implements the application-layer trait
+// ---------------------------------------------------------------------------
+
+/// Concrete [`ExploreService`] that the turn service calls.
+///
+/// Owns a shared `ToolCtx` and LLM credentials. Each call to `explore()`
+/// spawns 3 subagents in parallel with TUI workflow-tab visibility.
+pub struct ExploreServiceImpl {
+    tool_ctx: ToolCtx,
+    credentials: Credentials,
+}
+
+impl ExploreServiceImpl {
+    pub fn new(tool_ctx: ToolCtx, credentials: Credentials) -> Self {
+        ExploreServiceImpl {
+            tool_ctx,
+            credentials,
+        }
+    }
+}
+
+impl ExploreService for ExploreServiceImpl {
+    fn explore<'a>(
+        &'a self,
+        query: &'a str,
+        workspace_root: &'a str,
+        turn_events: &'a Arc<Mutex<VecDeque<TurnEvent>>>,
+    ) -> Pin<Box<dyn Future<Output = Result<ExploreOutput>> + Send + 'a>> {
+        Box::pin(async move {
+            let context = run_explore_phase(
+                query,
+                workspace_root,
+                &self.tool_ctx,
+                &self.credentials,
+                turn_events,
+            )
+            .await?;
+
+            Ok(ExploreOutput {
+                context_messages: vec![context],
+                summary: format!("{EXPLORE_AGENT_COUNT} explore agents dispatched"),
+            })
+        })
+    }
+}
+
+// ---------------------------------------------------------------------------
+//  Helpers for pushing workflow events
+// ---------------------------------------------------------------------------
+
+fn push_event(events: &Arc<Mutex<VecDeque<TurnEvent>>>, event: TurnEvent) {
+    if let Ok(mut q) = events.lock() {
+        q.push_back(event);
+    }
+}
+
+fn emit_pending(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str) {
+    push_event(
+        events,
+        TurnEvent::WorkflowAgentUpdate {
+            agent_id: agent_id.to_string(),
+            agent_name: display.to_string(),
+            status: AgentStatus::Pending,
+        },
+    );
+}
+
+fn emit_running(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str) {
+    push_event(
+        events,
+        TurnEvent::WorkflowAgentUpdate {
+            agent_id: agent_id.to_string(),
+            agent_name: display.to_string(),
+            status: AgentStatus::Running,
+        },
+    );
+}
+
+fn emit_completed(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str) {
+    push_event(
+        events,
+        TurnEvent::WorkflowAgentUpdate {
+            agent_id: agent_id.to_string(),
+            agent_name: display.to_string(),
+            status: AgentStatus::Completed,
+        },
+    );
+}
+
+fn emit_failed(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str, msg: &str) {
+    push_event(
+        events,
+        TurnEvent::WorkflowAgentUpdate {
+            agent_id: agent_id.to_string(),
+            agent_name: display.to_string(),
+            status: AgentStatus::Failed(msg.to_string()),
+        },
+    );
+}
+
+// ---------------------------------------------------------------------------
+//  Core orchestration
+// ---------------------------------------------------------------------------
+
+/// Spawn `EXPLORE_AGENT_COUNT` subagents in parallel, emit workflow events
+/// for the TUI tab, join, and consolidate.
+async fn run_explore_phase(
+    query: &str,
+    workspace_root: &str,
+    tool_ctx: &ToolCtx,
+    credentials: &Credentials,
+    turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
+) -> Result<String> {
+    // ── 1. Emit Pending for all agents (appears instantly in workflow tab) ─
+    for (i, &id) in EXPLORE_IDS.iter().enumerate() {
+        emit_pending(turn_events, id, EXPLORE_LABELS[i]);
+    }
+
+    // ── 2. Prepare directives ───────────────────────────────────────────
+    let mut directives: Vec<String> = Vec::with_capacity(EXPLORE_AGENT_COUNT);
+    for (i, &d) in EXPLORE_DIRECTIVES.iter().enumerate() {
+        let mut d = d.to_string();
+        if i == 2 {
+            d.push_str(&format!("\n\nThe user's current query is: \"{query}\""));
+        }
+        d.push_str(&format!("\n\nWorkspace root: {workspace_root}"));
+        directives.push(d);
+    }
+
+    // ── 3. Spawn all agents on threads ──────────────────────────────────
+    let mut handles: Vec<(usize, thread::JoinHandle<Result<String>>)> =
+        Vec::with_capacity(EXPLORE_AGENT_COUNT);
+
+    for i in 0..EXPLORE_AGENT_COUNT {
+        emit_running(turn_events, EXPLORE_IDS[i], EXPLORE_LABELS[i]);
+
+        let ctx = SubagentContext::new(
+            directives[i].clone(),
+            tool_ctx.clone(),
+            "read".to_string(),
+            credentials.base_url.clone(),
+            credentials.api_key.clone(),
+            credentials.model.clone(),
+        );
+
+        let directive = directives[i].clone();
+        let tc = tool_ctx.clone();
+
+        let handle = thread::spawn(move || {
+            let rt = tokio::runtime::Runtime::new()
+                .context("create explore subagent tokio runtime")?;
+            rt.block_on(run_agent(ctx, &directive, AccessTier::Read, tc))
+        });
+
+        handles.push((i, handle));
+    }
+
+    // ── 4. Join handles via spawn_blocking ──────────────────────────────
+    let turn_events_clone = Arc::clone(turn_events);
+    let results: Vec<(usize, String, bool)> = tokio::task::spawn_blocking(move || {
+        let mut out = Vec::with_capacity(EXPLORE_AGENT_COUNT);
+        for (i, handle) in handles {
+            let entry = match handle.join() {
+                Ok(Ok(output)) => {
+                    info!(agent = i, "explore subagent completed");
+                    emit_completed(&turn_events_clone, EXPLORE_IDS[i], EXPLORE_LABELS[i]);
+                    (i, output, true)
+                }
+                Ok(Err(e)) => {
+                    warn!(agent = i, error = %e, "explore subagent failed");
+                    emit_failed(&turn_events_clone, EXPLORE_IDS[i], EXPLORE_LABELS[i], &e.to_string());
+                    (i, format!("Error: {e}"), false)
+                }
+                Err(e) => {
+                    warn!(agent = i, error = ?e, "explore subagent panicked");
+                    emit_failed(&turn_events_clone, EXPLORE_IDS[i], EXPLORE_LABELS[i], "thread panicked");
+                    (i, format!("Thread panic: {e:?}"), false)
+                }
+            };
+            out.push(entry);
+        }
+        out
+    })
+    .await
+    .context("explore join task panicked")?;
+
+    // ── 5. Build consolidated context ───────────────────────────────────
+    Ok(build_explore_context(&results))
+}
+
+// ---------------------------------------------------------------------------
+//  Consolidation
+// ---------------------------------------------------------------------------
+
+/// Format explore results as a system-level context message.
+fn build_explore_context(results: &[(usize, String, bool)]) -> String {
+    let success_count = results.iter().filter(|r| r.2).count();
+    let total = results.len();
+
+    let mut msg = format!(
+        "[Explore Phase — {success_count}/{total} agents succeeded]\n\n"
+    );
+
+    for (i, output, success) in results {
+        let label = EXPLORE_LABELS.get(*i).unwrap_or(&"❓ Unknown");
+        if *success {
+            msg.push_str(&format!("=== {label} ===\n{output}\n\n"));
+        } else {
+            msg.push_str(&format!("=== {label} (FAILED) ===\n{output}\n\n"));
+        }
+    }
+
+    msg
+}
@@ -22,6 +22,7 @@
 pub mod arch_audit;
 pub mod code_quality;
 pub mod commit;
+pub mod explore;
 pub mod skills;

 use anyhow::Result;
@@ -35,7 +35,7 @@ impl EmbeddedSkills {
                match entry {
                    DirEntry::Dir(sub) => walk(sub, skills),
                    DirEntry::File(file) => {
-                        if file.path().file_name().map_or(false, |n| n == "SKILL.md") {
+                        if file.path().file_name().is_some_and(|n| n == "SKILL.md") {
                            if let Some(parent) = file
                                .path()
                                .parent()
@@ -54,8 +54,8 @@ pub use zesdex_domain::*;
 use std::path::PathBuf;
 use std::sync::Arc;

-/// Which kind of caller (main agent vs. subagent vs. reviewer) is
-/// invoking a tool, used to scope permissions and tag log/output paths.
+// Which kind of caller (main agent vs. subagent vs. reviewer) is
+// invoking a tool, used to scope permissions and tag log/output paths.
 // ---------------------------------------------------------------------------
 // TurnEvent & runtime types have been moved to zesdex_domain::agent
 // ---------------------------------------------------------------------------
@@ -2,9 +2,7 @@
 //! supporting both non-streaming and SSE-streaming requests with automatic retry.

 use rand_core::RngCore;
-use std::sync::atomic::AtomicBool;
 use std::time::Duration;
-use std::future::Future;

 use zesdex_domain::core::{
    ChatMessage, ChatRequest, ChatResponse, SseParser, StreamEvent, StreamOptions, ToolDef,
@@ -2,7 +2,6 @@ use std::future::Future;
 use anyhow::Result;
 use zesdex_application::agent::ToolExecutor;
 use crate::tools::{all_tools, Tool, ToolCtx};
-use tracing::debug;

 pub struct InfrastructureToolExecutor {
    ctx: ToolCtx,
@@ -32,17 +31,6 @@ impl ToolExecutor for InfrastructureToolExecutor {
        async move {
            match tool_opt {
                Some(tool) => {
-                    // Tool::run is synchronous, so we run it in a blocking task if needed
-                    // For now, since they run fast and we are transitioning, we can just block in place.
-                    // Or tokio::task::spawn_blocking:
-                    let tool_name = tool.name().to_string();
-                    let t_ctx = ctx.clone();
-                    let t_args = args.clone();
-                    
-                    // Because Tool isn't easily cloned, we might just block on the current thread, 
-                    // or use tokio::task::block_in_place if we're in a tokio runtime.
-                    // But `tool.run` takes `&self`, and we have `&self` borrowed.
-                    // For now we just call it directly.
                    tokio::task::block_in_place(move || {
                        tool.run(&ctx, &args)
                    })
@@ -44,6 +44,7 @@ pub fn all_tools() -> Vec<Box<dyn super::Tool>> {
        Box::new(super::web_search::WebSearch),
        Box::new(super::semantic_search::SemanticSearch),
        Box::new(super::semantic_search::RebuildIndex),
+        Box::new(super::semantic_search::ListSymbols),
        Box::new(super::parallel_delegate::ParallelDelegate),
        // ── Best-practice tools (built-in) ─────────────────────────
        Box::new(super::best_practice::BestPractice),
@@ -14,7 +14,7 @@ use crate::tools::{arg_str, Tool, ToolCtx};
 use crate::workflow::engine::execution::execute_workflow;
 use crate::workflow::hive_mind::cycle::execute_cycle;
 use crate::workflow::hive_mind::synthesis::synthesize_consensus;
-use zesdex_domain::workflow::{CognitiveCycle, NodeDirective, NodeOutput, WorkflowScript};
+use zesdex_domain::workflow::{CognitiveCycle, NodeDirective, NodeOutput};

 /// Execute a multi-step workflow defined in YAML.
 ///
@@ -23,7 +23,7 @@ fn resolve_api_key(state: &AppStateRest, provider_name: &str) -> String {
    if let Some(key) = state.settings.api_keys.get(provider_name) {
        return key.clone();
    }
-    if let Some(ref cfg) = state.app_config.providers.get(provider_name) {
+    if let Some(cfg) = state.app_config.providers.get(provider_name) {
        if let Some(ref default_key) = cfg.default_api_key {
            if !default_key.is_empty() {
                return default_key.clone();
@@ -110,6 +110,11 @@ pub fn spawn_agent_turn(state: &mut AppStateRest, text: String) {
        api_base: api_base.clone(),
    };

+    // Clone credentials before moving into LlmClient.
+    let explore_api_key = api_key.clone();
+    let explore_model = model.clone();
+    let explore_base_url = api_base.clone().unwrap_or_else(|| "https://api.openai.com/v1".to_string());
+
    let client = std::sync::Arc::new(LlmClient::new(api_key, model, api_base));

    let tool_ctx = ToolCtx::builder()
@@ -118,13 +123,30 @@ pub fn spawn_agent_turn(state: &mut AppStateRest, text: String) {
        .turn_events(turn_events)
        .build();

+    // Clone ToolCtx for the explore service (before moving into executor).
+    let explore_ctx = tool_ctx.clone();
+
    let tool_executor =
        std::sync::Arc::new(InfrastructureToolExecutor::new(tool_ctx));

    let tools = all_tools();
    let defs = tool_defs(&tools);

-    let turn_service = AgentTurnServiceImpl::new(client, tool_executor, defs);
+    // Wire the mandatory explore phase (3+ parallel subagents).
+    let explore_creds = zesdex_infrastructure::best_practice::explore::Credentials {
+        base_url: explore_base_url,
+        api_key: explore_api_key,
+        model: explore_model,
+    };
+    let explore_service = std::sync::Arc::new(
+        zesdex_infrastructure::best_practice::explore::ExploreServiceImpl::new(
+            explore_ctx,
+            explore_creds,
+        ),
+    );
+
+    let turn_service = AgentTurnServiceImpl::new(client, tool_executor, defs)
+        .with_explore(explore_service);

    tokio::spawn(async move {
        let _ = turn_service.run_turn(params).await;
@@ -29,7 +29,7 @@ const SIDEBAR_MIN_WIDTH: u16 = 90;
 /// This separates cache mutation from rendering so `draw` can take
 /// `&AppStateRest` (required by `terminal.draw` closure constraints).
 pub fn pre_render(state: &mut AppStateRest) {
-    let mut chat_comp = chat::ChatComponent::default();
+    let mut chat_comp = chat::ChatComponent;
    chat_comp.pre_render(state);
 }

@@ -67,18 +67,18 @@ pub fn draw(frame: &mut Frame, state: &AppStateRest) {
        let overlay = state.misc.overlay;
        overlays::render_overlay(frame, chat_area, overlay, state);
    } else {
-        let mut chat_comp = chat::ChatComponent::default();
+        let mut chat_comp = chat::ChatComponent;
        chat_comp.draw(frame, chat_area, state);
    }

-    let mut input_comp = input::InputComponent::default();
+    let mut input_comp = input::InputComponent;
    input_comp.draw(frame, input_area, state);

-    let mut status_comp = status::StatusBarComponent::default();
+    let mut status_comp = status::StatusBarComponent;
    status_comp.draw(frame, status_area, state);

    if let Some(sidebar_rect) = sidebar_area {
-        let mut sidebar_comp = sidebar::SidebarComponent::default();
+        let mut sidebar_comp = sidebar::SidebarComponent;
        sidebar_comp.draw(frame, sidebar_rect, state);
    }

@@ -11,7 +11,7 @@
  };

  outputs = { self, nixpkgs, flake-utils, rust-overlay }:
-    flake-utils.lib.eachDefaultSystem (system:
+    flake-utils.lib.eachSystem [ "x86_64-linux" ] (system:
      let
        overlays = [ (import rust-overlay) ];
        pkgs = import nixpkgs { inherit system overlays; };