You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2026/10/01 13:18:46 UTC
(camel) 01/01: chore: docs - split the camel-jbang tui page into sub pages (diagram, observe, AI panel, AI agents, settings) with key features and screenshots
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch quick-fix/tui-docs-split
in repository https://gitbox.apache.org/repos/asf/camel.git
commit c0349c3fd5d0fb20c75c118ef1d573009ad8761c
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Thu Oct 1 15:18:30 2026 +0200
chore: docs - split the camel-jbang tui page into sub pages (diagram, observe, AI panel, AI agents, settings) with key features and screenshots
Co-Authored-By: Claude Opus 5.5 (1M context) <no...@anthropic.com>
Signed-off-by: Claus Ibsen <cl...@gmail.com>
---
.../images/jbang/camel-tui-ai-panel-answer.png | Bin 0 -> 481846 bytes
.../ROOT/images/jbang/camel-tui-diagram-route.png | Bin 0 -> 413068 bytes
.../images/jbang/camel-tui-diagram-topology.png | Bin 0 -> 399860 bytes
.../images/jbang/camel-tui-main-quarkus-source.png | Bin 0 -> 497912 bytes
.../jbang/camel-tui-observe-error-diagram.png | Bin 0 -> 437483 bytes
.../images/jbang/camel-tui-observe-waterfall.png | Bin 0 -> 450839 bytes
.../ROOT/images/jbang/camel-tui-theme-latte.png | Bin 0 -> 368099 bytes
docs/user-manual/modules/ROOT/nav.adoc | 5 +
.../modules/ROOT/pages/camel-jbang-ai.adoc | 2 +-
.../ROOT/pages/camel-jbang-tui-ai-agents.adoc | 269 ++++
.../modules/ROOT/pages/camel-jbang-tui-ai.adoc | 394 ++++++
.../ROOT/pages/camel-jbang-tui-diagram.adoc | 176 +++
.../ROOT/pages/camel-jbang-tui-observe.adoc | 309 +++++
.../ROOT/pages/camel-jbang-tui-settings.adoc | 224 ++++
.../ROOT/pages/camel-jbang-tui-source-editor.adoc | 4 +-
.../modules/ROOT/pages/camel-jbang-tui.adoc | 1314 +-------------------
16 files changed, 1413 insertions(+), 1284 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-ai-panel-answer.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-ai-panel-answer.png
new file mode 100644
index 000000000000..8c2fb2fe9d20
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-ai-panel-answer.png differ
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-diagram-route.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-diagram-route.png
new file mode 100644
index 000000000000..3b0e6b836040
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-diagram-route.png differ
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-diagram-topology.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-diagram-topology.png
new file mode 100644
index 000000000000..e2ce070a1017
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-diagram-topology.png differ
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-main-quarkus-source.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-main-quarkus-source.png
new file mode 100644
index 000000000000..7bf5d39059e5
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-main-quarkus-source.png differ
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-observe-error-diagram.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-observe-error-diagram.png
new file mode 100644
index 000000000000..48729abdf42e
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-observe-error-diagram.png differ
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-observe-waterfall.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-observe-waterfall.png
new file mode 100644
index 000000000000..0d03d32b08ca
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-observe-waterfall.png differ
diff --git a/docs/user-manual/modules/ROOT/images/jbang/camel-tui-theme-latte.png b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-theme-latte.png
new file mode 100644
index 000000000000..c163403333e6
Binary files /dev/null and b/docs/user-manual/modules/ROOT/images/jbang/camel-tui-theme-latte.png differ
diff --git a/docs/user-manual/modules/ROOT/nav.adoc b/docs/user-manual/modules/ROOT/nav.adoc
index 3e2575e23f54..f3a51c5d0dc2 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -12,6 +12,11 @@
*** xref:camel-jbang-test.adoc[Camel Testing Plugin]
*** xref:camel-jbang-tui.adoc[Camel TUI]
**** xref:camel-jbang-tui-source-editor.adoc[Camel TUI Source Editor]
+**** xref:camel-jbang-tui-diagram.adoc[Camel TUI Diagram]
+**** xref:camel-jbang-tui-observe.adoc[Camel TUI Observing Integrations]
+**** xref:camel-jbang-tui-ai.adoc[Camel TUI AI Panel]
+**** xref:camel-jbang-tui-ai-agents.adoc[Camel TUI and AI Agents]
+**** xref:camel-jbang-tui-settings.adoc[Camel TUI Actions, Settings and Themes]
*** xref:camel-jbang-mcp.adoc[Camel MCP Server]
*** xref:camel-jbang-container.adoc[Camel CLI container]
** xref:camel-maven-plugin.adoc[Camel Maven Plugin]
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc
index 67e24c5987c4..2526cfb71d1c 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-ai.adoc
@@ -276,7 +276,7 @@ of reloading the model, and for a context window (`num_ctx`) chosen once per mod
The tool-calling prompt alone is about 4.5k tokens, which is why 32k is the floor: Ollama's own default
on machines with less than 24 GB is 4k and would truncate it. Keep all your Ollama clients on the same
value; if you set `OLLAMA_CONTEXT_LENGTH` for the CLI, set it for `ollama serve` too. The TUI's Ollama
-tab shows the window in use, and xref:camel-jbang-tui.adoc#_working_with_a_local_ollama_model[Working
+tab shows the window in use, and xref:camel-jbang-tui-ai.adoc#_working_with_a_local_ollama_model[Working
with a local Ollama model] explains how the AI panel manages its history inside it.
=== Using an OpenAI-compatible local server
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-ai-agents.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-ai-agents.adoc
new file mode 100644
index 000000000000..0b5d04b27567
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-ai-agents.adoc
@@ -0,0 +1,269 @@
+= Camel TUI and AI Agents
+
+The TUI is also a tool for AI coding agents: over MCP an agent sees the running integrations as you do and can act
+on them, and over ACP a coding agent such as Claude Code drives the TUI's AI panel. Every change to a file waits for
+your confirmation.
+
+See xref:camel-jbang-tui.adoc[Camel TUI] for getting started and the other pages.
+
+== Key Features
+
+* <<_why_this_matters,*Same view as you*>> -- routes, statistics, traces, errors, logs and sources
+* <<_enabling_mcp,*MCP server*>> -- camel tui --mcp, on localhost only
+* <<_using_a_coding_agent_acp,*Coding agents over ACP*>> -- a coding agent drives the AI panel
+* <<_what_ai_agents_can_do,*Navigate, control and teach*>> -- switch tabs, control routes, draw on the screen
+* <<_editing_source_files_from_an_ai_agent,*Edits you confirm*>> -- or watch them typed in the editor (live mode)
+* <<_example_workflows,*Example workflows*>> -- what to ask an agent
+
+== Why This Matters
+
+When an AI agent connects to the TUI via MCP, it gains the same level of visibility that you
+have -- and can act on it. The agent can:
+
+* *Read everything* -- route topology, statistics, message traces, errors, logs, source files,
+ health checks, and JVM metrics
+* *Navigate and control* -- switch tabs, select routes, start/stop routes, send test messages,
+ change log levels
+* *Teach and present* -- the AI can control the TUI screen to walk you through concepts,
+ highlight areas of interest, draw annotations, and take screenshots. It can circle a failing
+ route, draw arrows between connected endpoints, and add explanatory text labels -- turning the
+ TUI into a live whiteboard for pair-programming
+* *Self-troubleshoot* -- when something fails, the AI can autonomously inspect the error,
+ read the message trace, correlate with route statistics, and produce a diagnostic report
+ with annotated screenshots showing exactly where and why the failure occurred
+
+== Enabling MCP
+
+[source,bash]
+----
+camel tui --mcp
+----
+
+This starts an MCP server on `localhost:8123` (configurable with `--mcp-port`).
+The server is bound to `127.0.0.1` only -- it never listens on external interfaces.
+
+When MCP is active, the TUI footer shows the connection status.
+Use *F2* -> _MCP Info_ to see server details and _MCP Log_ to view the tool call history.
+
+== Status document resources
+
+Every running integration keeps a full status document in `~/.camel/<pid>-status.json`, written
+once a second by `camel-cli-connector`. The tabs show a digest of it; the MCP server exposes the
+whole document as resources so an agent can fetch exactly the section it needs instead of
+paging through tabs:
+
+* `camel://log/<pid>` -- the last 200 lines of the integration's log (`~/.camel/<pid>.log`);
+ `camel://log/<pid>?lines=<n>` for a different tail length (up to 5000). The Log tab shows only a
+ window of this file, so an agent that needs to know which lines the user is looking at should
+ use the `tui_get_screen` tool instead.
+* `camel://status/<pid>` -- the whole document
+* `camel://status/<pid>/<section>` -- one top-level section, for example `context` (name, version,
+ state, uptime, start timestamp, statistics), `runtime`, `routes`, `endpoints`, `healthChecks`,
+ `properties`, `main-configuration`, `routeController`, `memory`, `threads`, `gc` or `events`
+
+`resources/list` enumerates the log, the document and its sections for every monitored
+integration, and `resources/templates/list` describes the URI shapes. The same data is available to the
+F8 AI panel (and as an MCP tool) through `tui_get_status`, which takes a `section` argument and
+returns that section only; pass `sections` to list what the document contains. Sections such as
+`events` can be large, so ask for the one you need.
+
+== Using a coding agent (ACP)
+
+Instead of talking to a model directly, the AI panel can hand the conversation to an external coding agent that
+speaks the https://agentclientprotocol.com[Agent Client Protocol] (ACP). The TUI starts the agent as a subprocess,
+gives it the TUI's own MCP server, and shows the agent's answer, tool calls and questions in the panel. The agent
+drives the TUI through the same `tui_*` tools that external MCP clients use, and can also read and edit your
+route sources with its own tools.
+
+Press *Ctrl+P* in the AI panel and pick one of the agents:
+
+[options="header"]
+|===
+| Provider | Command the TUI runs | Before the first question
+| `acp:claude` | `npx -y @agentclientprotocol/claude-agent-acp` | log in with the `claude` CLI, or set `ANTHROPIC_API_KEY`
+| `acp:codex` | `npx -y @agentclientprotocol/codex-acp` | `codex login`, or set `OPENAI_API_KEY`
+| `acp:bob` | `bob acp` | set `BOBSHELL_API_KEY`, or run `bob` once to sign in
+| `acp:qwen` | `qwen --acp` | set `OPENAI_API_KEY` and `OPENAI_BASE_URL`
+| `acp:opencode` | `opencode acp` | `opencode auth login`
+| `acp:dsh` | `npx -y @deepseek-ai/dsh --profile acp` | configure the model key in DeepSeek Harness (developer preview)
+| `acp:custom` | the value of `camel.tui.ai.acp.command` | depends on the agent
+|===
+
+The `npx` entries need Node.js 22 or newer (the Claude adapter requires it). The agent starts with your first
+question; the first start can take a while when `npx` has to download the adapter. Once the session is open the
+panel shows a two-row header with the agent's coloured glyph, the agent's name and version, the session id, the
+working directory and the number of commands it advertises. Use *F2* -> _Settings_ to make an
+agent the default provider or to set the custom command (a plain command line split on whitespace, no quoting).
+
+The MCP server is started automatically on a random localhost port when an agent needs it, so `--mcp` is not
+required. *F2* -> _MCP Info_ shows the port and the tool calls the agent makes. Like the server started with
+`--mcp`, it is bound to `127.0.0.1` with no authentication, and it rejects requests that carry an `Origin`
+header (so a web page cannot reach it) or that are not JSON.
+
+Permissions: calls to the TUI's read-only tools (the `tui_get_*` tools, catalog documentation, expression
+evaluation, locate, validate) are approved without asking. So is `camel_write_file` while the write mode is
+`confirm` or `live`, because the TUI itself asks before the file is touched (the diff dialog or the live replay
+in the Source editor); with `/write auto` the permission popup is the only question and stays. A tool that
+changes anything else, such as `camel_control`, `tui_send_message` or `tui_execute_sql`, opens the same popup as
+any other request; answering "Always allow" makes it a one-time question per tool. For anything else the agent
+wants to do, such as editing a file with its own tools or running a command, a popup shows the agent's options;
+*Enter* selects, *Esc* rejects that one call and lets the turn continue, and *Ctrl+C* cancels the whole turn.
+The preamble tells the agent to edit route sources through `camel_write_file` rather than its own file tools, so
+that you see the diff or watch the edit; when it still asks to edit a file directly, the popup says so and *Esc*
+sends it back to `camel_write_file`.
+"Always allow" choices are remembered by the agent for the session. The model, reasoning settings and any
+"always allow" rules are configured in the agent, not in the TUI; `/model` only reports the agent in use.
+
+The agent's own slash commands, for example Claude Code skills, appear as `/agent:<name>` in the `/` completion
+hints once the session is open; `/agent:` alone lists them. `/agent:<name> …` always reaches the agent, even when
+the name is also a panel command (`/agent:clear` clears the agent's context, `/clear` the panel). Anything else
+starting with `/` that is not a panel command is sent to the agent as is.
+
+The panel's own `/retry` resends the last question (or `/agent:` command) to the agent. `/context` shows the agent,
+its session, working directory, MCP server and the size of the preamble instead of a model history, and `/prompt`
+shows that preamble, sent once per session ahead of the first prompt. `/compact` and `/tools` do not apply while an
+agent is selected: the agent manages its own history and reaches the camel-tui tools through the MCP server; the panel
+says so and points to `/agent:compact` when the agent offers that command.
+
+If the agent asks for authentication and can sign you in itself, the TUI triggers that flow once; otherwise the
+panel shows the login command from the table above.
+
+NOTE: Gemini CLI, Google Antigravity and Pi are not offered as presets. Gemini CLI stopped serving personal Google
+accounts in June 2026, Antigravity's CLI has no ACP mode yet, and Pi's community adapter does not pass MCP servers
+through. Any ACP agent can still be tried through `acp:custom`.
+
+== Connecting an AI Agent
+
+To connect Claude Code to the TUI, add the MCP server to your project configuration
+(`.mcp.json` in your project root):
+
+[source,json]
+----
+{
+ "mcpServers": {
+ "camel-tui": {
+ "type": "url",
+ "url": "http://localhost:8123/mcp"
+ }
+ }
+}
+----
+
+== What AI Agents Can Do
+
+The MCP server exposes two kinds of tools. The `camel_` tools are the Camel authoring set shared with the
+`camel mcp` server (see xref:camel-jbang-mcp.adoc[]): catalog documentation with the endpoint URI rules and the
+simple syntax (`camel_catalog_doc`, `camel_catalog_find`), source validation (`camel_validate_source`), reading
+and writing the source files (`camel_get_files`, `camel_write_file`), running an integration in dev mode and
+controlling it (`camel_run`, `camel_control`), its log and failed exchanges (`camel_get_log`, `camel_get_errors`),
+expression evaluation (`camel_eval_expression`) and error diagnosis (`camel_error_diagnose`). They are defined
+once in the Camel CLI, so an agent gets the same tools, names and answers through either server; in the TUI
+they work on the selected integration unless a `directory` or `name` argument says otherwise, and a write goes
+through the TUI's confirm dialog or live replay. The `tui_` tools are the ones only the TUI can offer, organized
+by purpose:
+
+* *Observe* -- read the screen, get structured state, query tables/logs/errors/traces/topology/diagram/files,
+ list the running infra services (brokers, databases) and read their logs, read the performance of the
+ local Ollama server (`tui_get_ollama`: loaded model, tokens per second, context fill, host load, request log)
+* *Navigate* -- switch tabs, select integrations, select routes, send keystrokes, apply filters
+* *Act* -- send test messages to endpoints, start/stop/restart routes, change log levels,
+ list and launch the bundled examples, start/stop/restart infra services, run any entry of
+ the *F2* actions menu by its label
+* *Edit* -- write a source file in the integration's source directory (`camel_write_file`), see below
+* *Annotate* -- locate text and diagram nodes by coordinates, draw shapes (boxes, highlights,
+ arrows, underlines, text labels), show captions with typewriter animation
+* *Present* -- take screenshots, record tape sessions, control demo pacing
+
+== Editing source files from an AI agent
+
+The TUI is for prototyping, human and AI together, so an agent (the built-in *F8* panel or an
+external MCP client) can change the routes it is looking at. `camel_get_files` tells the agent where
+the sources are, which differs with how the integration was started (plain files, `--source-dir`,
+an example extracted to a temporary folder, or an exported project), and whether editing makes
+sense: `devMode` (changes are reloaded automatically), `temporary` (a copy that is lost when the
+integration stops) and an `editing` hint. `camel_write_file` then writes the complete new content of
+a file in that directory.
+
+An integration started with `--runtime=spring-boot` or `--runtime=quarkus` runs from an exported Maven
+project, where the routes sit under `src/main/resources/camel` rather than next to a `pom.xml`. The
+listing understands that layout: it names the route and configuration files first, lists every file
+with its path relative to the project (build output skipped), and maps each running route to its file
+and line, so the agent reads the right file in one call instead of guessing names. File paths given to
+`camel_get_files` and `camel_write_file` are relative to that directory and may name a subdirectory.
+
+Every write is confirmed in the TUI first: a dialog names the file, the directory and the size of the
+change (`+3 -1` lines); press *d* to see the change as a unified diff, with removed lines on red and
+added lines on green like the Source tab's *F7* diff, and scroll it with the arrow keys; *Enter*, *Esc* or
+*d* returns to the summary. In the summary *Enter* applies the write and *Esc* rejects it, in which case the
+agent is told that the file is unchanged and not to retry. The dialog cannot be skipped by the agent on
+its own: `confirm=false` is honoured only after you switched to `/write auto` in the AI panel (the default
+`/write confirm` shows the dialog for every write, whatever the agent passes). Only plain file names in the source
+directory are accepted; the tool cannot write elsewhere, and there is no git integration, so the
+worst case is a wrong route file in a folder you are watching.
+
+Before writing, an agent can check its content with `camel_validate_source`, which runs the same checks as
+the Source tab's save: YAML routes against the Camel YAML DSL schema (a misspelled option such as `logLevel`
+instead of `loggingLevel` is reported) plus endpoint URIs and simple expressions, Java and XML routes read into
+the Camel model with the same endpoint and simple checks, and `.properties` files against the catalog of
+`camel.*` and Spring Boot options. `camel_write_file` runs that validation itself and
+refuses to write an invalid file, returning the errors instead, so a model fixes them rather than the user
+finding them in the log after the reload. Both tools are part of the core
+tool set, so local models (Ollama) get them as well.
+
+Simple expressions get two more helpers, because they are what a small model gets wrong most often
+(functions belong inside the `${...}` placeholder, operators between placeholders: `${header.user} ?: 'Guest'`,
+not `${header.user ?: 'Guest'}`). `camel_catalog_doc` for the `simple` language returns those syntax rules
+together with the catalog's functions and operators (their count and names by group, or with `optionsFilter`
+the matching ones with parameters and examples), and `docPage` serves the operators, functions, OGNL and
+advanced documentation pages. `camel_eval_expression` evaluates an expression inside the running integration,
+like `camel cmd eval`, or locally when no integration is selected, and returns the value or the parser error,
+so the agent can try an expression before it answers or writes it. Component lookups get the same treatment for endpoint URIs: every endpoint option
+says whether it is part of the URI path or a query parameter, and the result spells out the URI rules for
+that component (its path options, the `?option=value&option=value` form, the YAML `uri` plus `parameters`
+form, placeholders, `RAW()`, and that component options belong in `application.properties`). With
+`endpoint` the same tool checks a URI against the catalog, the way the YAML validator does on a write:
+unknown options with the closest real names, values that are not among the allowed ones, missing path
+parts, consumer options on a producer endpoint and the like, plus the options the URI uses with their
+documentation, so the agent can check an endpoint before it answers or writes it.
+
+=== Watching the AI edit (live mode)
+
+With `/write live` the change is not shown as a diff but replayed in the Source tab's editor: the AI
+panel hides so the editor has the whole screen, the file opens in edit mode, the cursor jumps to the
+first change, removed lines disappear and added lines are typed at a readable pace. The AI panel comes
+back once you have saved or discarded. This is meant for learning Camel and the YAML DSL: you see the edit land in
+the full, syntax-highlighted file and can look up what the new lines mean. Every change is its own step,
+even when changes sit a line apart, and between them the replay pauses: *Enter* continues with the next change, *Esc* stops (what was typed stays in the editor), any
+other key finishes the current change at once, and *F4* (the editor's edit key) hands the keyboard to you
+so you can edit yourself; *F9* then continues with the remaining changes. Those are located by their surrounding lines,
+so your own edits elsewhere in the file shift them rather than break them; a change whose surroundings
+you edited is skipped and reported to the agent. When the replay is over you review with *F7* and
+save with *Ctrl+S* or *F5*, which is the confirmation, or discard with *Esc*. The agent waits until then
+and is told what was applied, what was skipped, and the content of the saved file if you changed it.
+
+An edit (`camel_edit_file`, which the agent uses to change a file without rewriting it) goes the same way: the
+snippet is replaced in the file's content and the result is confirmed or replayed like any write, so what you see
+in the editor is the finished file either way.
+
+While the replay pauses you can also ask the agent about the change it just made: *F8* opens the AI panel
+with the question prefilled (`About edit 2 of 3:`), you complete it and press *Enter*. The waiting
+`camel_write_file` call returns to the agent with the question, the edits applied so far and the editor's
+content, and the agent answers in the same turn -- nothing is written meanwhile. Close the panel with *F8*
+(or *Esc* to leave without asking) and the pause continues where it was. If your question makes the agent
+revise the change, its next `camel_write_file` of the same file continues in the editor from the current
+content instead of starting over. If you save or discard without the agent being involved again, it is
+told what became of the edit with your next question.
+
+== Example Workflows
+
+* _"What routes are failing and why?"_ -- The agent reads the errors tab, correlates with
+ route statistics, steps through the failing exchange in the Inspect tab, and explains
+ the root cause with annotated screenshots.
+* _"Show me how this message flows through the system"_ -- The agent navigates to the Inspect tab,
+ opens the diagram replay, steps through each processor, and highlights the path on the
+ topology while explaining what happens at each step.
+* _"Highlight the bottleneck routes"_ -- The agent reads the route statistics, locates the
+ slowest routes on the diagram, draws red boxes around them, and adds labels with the
+ processing times.
+
+See xref:camel-jbang-mcp.adoc[Camel MCP Server] for more about MCP and AI integration with Camel.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-ai.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-ai.adoc
new file mode 100644
index 000000000000..a538bcb0a3ac
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-ai.adoc
@@ -0,0 +1,394 @@
+= Camel TUI AI Panel
+
+The AI panel (*F8*) lets you ask about your integrations in plain language: the AI sees what the TUI sees, reads the
+sources and the catalog, and can change files with your confirmation. It works with hosted models and with local
+models through Ollama, so nothing has to leave your machine.
+
+See xref:camel-jbang-tui.adoc[Camel TUI] for getting started and the other pages.
+
+== Key Features
+
+* <<_choosing_an_ai_provider,*Any provider*>> -- a hosted model or a local one through Ollama or an OpenAI-compatible server
+* <<_ai_panel_slash_commands,*Slash commands*>> -- run examples, change settings and steer the AI from the panel
+* <<_ai_project_overview,*Project overview*>> -- the AI explains the project once and the diagram shows it as capabilities
+* <<_ai_log,*AI log*>> -- what was asked, which tools ran and what they returned
+* <<_ollama,*Ollama tab*>> -- the local models, their context window and what is loaded
+
+== Choosing an AI provider
+
+Press *F8* to open the built-in AI prompt panel. The panel auto-detects a provider in this order:
+
+1. `ANTHROPIC_API_KEY` → Anthropic Claude
+2. `CLOUD_ML_REGION` + `ANTHROPIC_VERTEX_PROJECT_ID` → Vertex AI
+3. `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` → Azure OpenAI
+4. `GEMINI_API_KEY` → Google Gemini
+5. `OPENAI_API_KEY` → OpenAI
+6. `LLM_API_KEY` + optional `LLM_BASE_URL` → any OpenAI-compatible server
+7. Ollama at `localhost:11434` → local Ollama (auto-detected, no key needed)
+
+Press *Ctrl+P* inside the AI panel to switch provider or model at any time.
+
+A question can span several lines: *Ctrl+N* starts a new line (terminals deliver *Shift+Enter* and
+*Alt+Enter* as a plain *Enter*, so they cannot be used), pasted text keeps its line breaks, and *Up* and
+*Down* move between the lines of the question before they recall earlier prompts. *Enter* sends it.
+
+The same guidance, together with the provider that is currently detected, is available inside the TUI
+via *F2* -> _AI & MCP_ -> _Setup AI_. Use *F2* -> _Settings_ to pin a provider, model or base URL
+(`camel.tui.ai.provider`, `camel.tui.ai.model`, `camel.tui.ai.url`) regardless of the environment.
+`camel.tui.ai.acp.command` sets the command line of the custom ACP agent (`acp:custom`).
+
+image::jbang/camel-tui-ai-panel-answer.png[A local Ollama model explains why an order failed]
+
+=== Using Ollama (local, no API key)
+
+Install Ollama natively for best performance — the native binary uses GPU acceleration
+(Metal on macOS, CUDA/ROCm on Linux):
+
+[source,bash]
+----
+# macOS
+brew install ollama
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Pull a model — then open the TUI and press F8
+ollama pull qwen3.6:35b-a3b
+camel tui
+----
+
+Ollama at `localhost:11434` is auto-detected. No configuration needed.
+
+IMPORTANT: The F8 AI panel works by invoking built-in tools to inspect your running Camel process.
+Models smaller than ~14B do not reliably call tools and answer from training knowledge instead.
+Use at least a 14B model. Prefer a mixture-of-experts model such as `qwen3.6:35b-a3b`: with only
+3B parameters active per token it processes the tool-heavy prompt many times faster than a dense
+27B/32B model, so answers start in seconds instead of a minute.
+
+*Models that work well* (tool-calling capable, ≥14B, default Q4_K_M quantization):
+
+[options="header"]
+|===
+| Model | RAM | Notes
+| `qwen3.6:35b-a3b` | ~23 GB | Recommended: fastest prompt processing, needs 32 GB+
+| `qwen2.5:14b` | ~9 GB | Minimum for 16 GB machines
+| `qwen3.6:27b` | ~18 GB | Strong dense model, several times slower prompt processing
+| `qwen2.5:32b` | ~20 GB | Good quality, slow prompt processing
+| `hermes3:70b` | ~43 GB | Excellent tool calling, needs 64 GB+
+| `llama3.3:70b` | ~43 GB | Best open model, needs 64 GB+
+|===
+
+NOTE: `camel infra run ollama` runs Ollama in Docker and bypasses GPU acceleration,
+making inference significantly slower. Native install is preferred for development.
+
+NOTE: On Apple Silicon, use the default (GGUF) tags rather than the `-mlx` tags. The Ollama MLX
+engine cannot yet reuse the cached prompt for Qwen 3.x models, so every question re-processes the
+whole prompt, while the default engine reuses it and only processes what is new.
+
+=== Tool set for local models
+
+Every question sends the definitions of the `tui_*` tools the model may call, and a local model
+pays for each of them in prompt-processing time. The panel therefore sends only the core set of
+tools (state, tables, logs, errors, diagrams, topology, processor details, catalog docs, traces,
+spans, route control, sending messages, source files, infra services, navigation, log level and
+filters) to Ollama
+and to any provider on `localhost`, which roughly halves the prompt. Hosted providers get every
+tool, including the drawing, animation and automation tools. Use `/tools full` in the panel to send
+all tools to a local model too, `/tools core` to trim the set for a hosted one, pick *AI Tools* in
+*F2 -> Settings*, or set `camel.tui.ai.tools` in `.camel-cli.properties`. Ollama requests also ask the server to keep the
+model loaded for 30 minutes and for a context window of 32k or 64k (see <<_working_with_a_local_ollama_model>>;
+`OLLAMA_CONTEXT_LENGTH` overrides it), so follow-up questions reuse the cached prompt instead of reloading
+the model.
+
+=== Working with a local Ollama model
+
+A local model is not a slower version of a hosted one; it spends its time differently, and the TUI
+shows you where. This section explains what a question costs with Ollama and which knobs matter,
+with figures measured on an Apple M4 Pro (64 GB) running `qwen3.6:35b-a3b`.
+
+*How a question is spent.* Ollama answers in three phases, and every timing the TUI shows maps to one
+of them:
+
+1. *Load*: if the model is not in memory (first question, the keep-alive expired, or a request asked for
+ a different context size) Ollama starts a runner and loads the weights: 10 to 20 seconds for a 22 GB
+ model. The TUI asks Ollama to keep the model loaded for 30 minutes after each request.
+2. *Prefill*: the prompt (system prompt, tool definitions, conversation history, your question) is
+ processed in one batch, at roughly 600 to 700 tokens per second when nothing is cached.
+3. *Decode*: the answer is generated token by token, at 50 to 60 tokens per second for this model.
+
+The wait before anything appears, the time to first token, is load plus prefill. A cold first question
+therefore takes 20 seconds before the first word; a warm one under a second.
+
+*One question, many requests.* The panel answers by calling the `tui_*` tools, and every tool call the
+model makes costs a new request that sends the whole prompt again. A simple question can take 3 to 13
+requests. This is affordable only because Ollama caches the prompt prefix: the system prompt, the tool
+definitions and the history are identical from one step to the next, so each step prefills only the new
+tokens and takes about half a second. Across a session the cache hit is typically above 90%. The
+Ollama tab shows the request count per question as `×N` and the cache hit per question; a question
+with a high count and a short answer is the model exploring, which a smaller, sharper tool set reduces
+(see <<_tool_set_for_local_models>>).
+
+*The context window.* The TUI decides the window it asks Ollama for (`num_ctx`) once per model:
+
+1. `OLLAMA_CONTEXT_LENGTH` in the environment wins when set.
+2. If the model is already loaded, its window is adopted (raised to 32k when smaller), so the TUI never
+ makes Ollama reload a model another client is using. A request with a different `num_ctx` costs a
+ cold start and throws away everyone's prompt cache.
+3. Otherwise 64k when the model's weights plus the KV cache of a 64k window fit the machine's memory,
+ computed from what `ollama show` reports (layers, KV heads, head size), else 32k. Overshooting is
+ worse than being conservative: Ollama then moves layers to the CPU and generation slows to a crawl.
+
+The static prefix of system prompt and core tools is about 4.5k tokens, and each question with tool
+calls adds another 2k to 4k of history. The panel compacts the history once the prompt Ollama measured
+for the last request passes half the window, capped at half of 64k even when a larger window was
+adopted: every token of history is prefill time again after a cache loss (an idle unload after 30
+minutes, another client, a restart), and 64k at a few hundred tokens per second is already well over a
+minute. Compacting rewrites the history, which invalidates Ollama's prompt cache, so the request after
+a compaction prefills the whole prompt again: about 40 seconds for a 21k-token prompt. The panel
+therefore compacts local history rarely and then thoroughly, down to about a quarter of the window,
+and prints one line saying what it did and how long the next reply will take to start. `/compact` does
+the same on demand with the same line; `/context` shows the window, the compaction point and the last
+measured prompt; the panel title shows the fill as `ctx 34%`.
+
+*Choosing the model.* With no `camel.tui.ai.model` set the panel takes `llama3.2` when it is installed,
+otherwise the first installed model; run `/model <name>` in the panel or set *AI Model* in
+*F2 -> Settings* to pin one. The model must support tool calling and should have at least 14B
+parameters; a mixture-of-experts model such as `qwen3.6:35b-a3b` prefills several times faster than a
+dense model of similar quality, which is what matters for a tool-heavy prompt. *F2 -> Run Doctor* shows
+whether Ollama was found, which models are installed and whether they are large enough.
+
+*Where to look.* The <<_ollama>> tab is the instrument for all of the above: tokens per second live and
+per request, time to first token with cold starts marked, cache hit, how full the context window is
+and how it grows per question, GPU and process load, and one line per question with the requests it
+took, the question being answered right now on top with `working` as its reason and its time counting
+up, and a footer with the average per question. In the AI panel, `/context` prints what the next request will cost, `/usage` and *Ctrl+U* the
+session totals per question.
+
+*Remote and containerised Ollama.* Everything above applies to an Ollama on another host or inside
+`camel infra run ollama` as well, with two differences: the container runs without GPU acceleration,
+and the live runner state and host load on the Ollama tab need the server on the same machine.
+
+For the wider picture see the blog posts
+link:/blog/2026/09/camel-local-model-benchmark/[We had a frontier AI coach a small local model through Camel]
+on what a local model can do with Camel and what was changed to help it, and
+link:/blog/2026/09/camel-genai-observability-jbang/[Observe Your Camel AI Routes with GenAI OpenTelemetry]
+on observing routes that call Ollama.
+
+=== Using an OpenAI-compatible local server
+
+Set `LLM_API_KEY` and `LLM_BASE_URL` to connect to any OpenAI-compatible server
+(LM Studio, vLLM, llama.cpp, GPT4All, …):
+
+[source,bash]
+----
+export LLM_API_KEY=any-value
+export LLM_BASE_URL=http://localhost:1234
+camel tui
+----
+
+`OPENAI_BASE_URL` is also accepted as an alternative to `LLM_BASE_URL`.
+
+The panel uses the first model the server lists on `/v1/models`. To use another one, run
+`/model <name>` in the panel (`/model` alone lists what the server offers), set *AI Model* in
+*F2 -> Settings*, or set `camel.tui.ai.model`. The model must support tool calling, otherwise the
+panel answers from training data instead of inspecting your integration. When a request fails, the
+panel shows the HTTP status and the server's error message, for example a model that the server
+does not host.
+
+== AI panel slash commands
+
+When the AI panel is open, input that starts with `/` runs a local panel command instead of sending a question to the configured AI provider. `/provider` and `/model` are unavailable while a response or command is already in progress; the panel shows a message asking you to wait.
+
+Press *Tab* to complete a command name. After `++/model ++` *Tab* completes the model name against the
+models the current provider reports (the list is fetched in the background on the first press, so
+press *Tab* again once it has arrived), and after `/tools ` it completes `auto`, `core` or `full`.
+With several matches *Tab* fills in the common prefix and then cycles through them; *Shift+Tab*
+cycles backward.
+
+[cols="1,3",options="header"]
+|===
+| Command | Description
+
+| `/help` (`/h`)
+| Show the available slash commands.
+
+| `/provider` (`/p`)
+| Open the provider switcher.
+
+| `/model [model-name]` (`/m`)
+| Show the current model, or switch the session model.
+
+| `/write [confirm\|auto\|live]` (`/w`)
+| Show or switch how file writes by the model (`camel_write_file`) are handled. `confirm` (default) shows the confirm dialog for every write, whatever the model passes; `auto` lets the model skip the dialog with `confirm=false`; `live` replays the edit in the Source editor so you watch it happen (see below). The mode lasts for the session.
+
+| `/tools [auto\|core\|full]` (`/t`)
+| Show which tool set is sent to the model, or switch it. `auto` (default) sends the core set to local providers and every tool to hosted ones; the choice is saved as `camel.tui.ai.tools`.
+
+| `/context` (`/ctx`)
+| Show what the next request costs: provider and model, tool set, static prefix size, history size and the session total, and with Ollama the context window, the prompt size above which the history is compacted and the last measured prompt. Useful with local models, where prompt size is time.
+
+| `/compact`
+| Shrink the conversation history sent to the model right away: older tool results are cut to their first lines and the oldest turns are dropped. With a hosted provider the panel does this automatically after each answer for all but the latest turn. With Ollama or another `localhost` provider it waits until the prompt Ollama measured passes half the context window (see <<_working_with_a_local_ollama_model>>), then compacts thoroughly, because a local server can reuse its cached prompt on [...]
+
+| `/retry`
+| Send the last question again, starting from a clean turn in the model history.
+
+| `/usage [reset]` (`/u`)
+| Print the AI usage so far in the chat: requests, tokens in and out, average latency, one line per model (and per route when GenAI spans are observed), and the last request. *Ctrl+U* opens the full view with the per-question chart. `/usage reset` clears the counters and the chart without touching the conversation; GenAI spans recorded before the reset are hidden from the view as well.
+
+| `/copy` (`/y`), `/export` (`/e`)
+| The same as *Ctrl+Y* (copy the last response) and *Ctrl+E* (export the conversation to Markdown). Copying is code-aware: when the response has one fenced code block only the code is copied (without the fences and the prose, which is what selecting it with the mouse cannot give you because of the panel borders); when it has several, a picker lists the blocks with their language and size plus the whole response; when it has none, the whole response is copied.
+
+| `/prompt`
+| Show the system prompt the panel sends with every request.
+
+| `/clear` (`/c`)
+| Clear the AI conversation, usage counters, and model context without changing the provider or model.
+
+| `/close`
+| Close the AI panel.
+
+| `/quit` (`/exit`, `/q`, `/x`)
+| Exit the TUI.
+
+| `/run <camel run args>` (`/r`)
+| Run `camel run` with the provided arguments.
+
+| `/infra <camel infra args>` (`/i`)
+| Run `camel infra` with the provided arguments.
+
+| `/overview [refresh\|show\|apply]` (`/o`)
+| The <<_ai_project_overview,AI project overview>> of the selected integration's project: without an argument it shows the summary when it is up to date and asks the model to explain the project otherwise; `refresh` explains it again, `show` opens the summary file in the document viewer, `apply` puts the suggested route descriptions into the route sources.
+
+| `/send <endpoint> <message text \| @file>` (`/s`)
+| Send a message through `camel cmd send`. A body that is exactly one `@file` token is sent as `file:<path>`; inline `@file` text is sent literally.
+|===
+
+== AI project overview
+
+A route diagram of many routes becomes spaghetti quickly, above all when the routes have no
+`description`. `/overview` asks the model to explain the project of the selected integration (or the
+folder the TUI runs in): an overview of what it does, the business capabilities its routes implement,
+and a description of each route that has none. The facts come from the route sources, the same ones
+`camel overview` prints (see xref:camel-jbang-ai.adoc#_project_overview[Project overview]): routes,
+entry points, how routes connect, external systems and findings. The model gets them with excerpts of
+the routes (values of passwords, tokens and other sensitive options masked) in one request without
+tools, so a local model does it as well as a hosted one. It runs in the background and the answer
+appears in the panel.
+
+The answer is saved in `camel-summary.md` in the project directory, a Markdown file you can read,
+review and commit. The TUI treats it as the project's generated README: `/overview show`, or *s* in the
+Diagram tab, opens it rendered in the document viewer (*t* lists its sections), at the routes from the
+topology and at the Architecture section from the architecture view. The title says when the routes changed since
+the AI wrote its part. A project without a summary gets the facts derived from its sources, with a note
+on how to add the AI part. In the Overview tab a project with a summary shows the 📖 mark, as one with a
+README does. Its AI-assisted sections are marked `✦ AI-assisted` and kept apart from the
+sections derived from the sources, and the file records the model, the date and a fingerprint of the
+routes, so the TUI knows when the routes changed afterwards: `/overview` then explains them again.
+
+A route description comes in two parts: a short label, and a note of a sentence or two, the
+`description` and `note` of a route in the DSL. The model writes both for a route that lacks them.
+
+What an AI wrote is never shown as if it came from the source or the runtime. When a route has no
+description of its own, the *Routes* tab (with descriptions on, *n*) and the topology in the *Diagram*
+tab show the suggested label in italic, in the `ai-assisted` theme color, marked with `✦`. The *Info*
+panel beside the topology shows the whole label and note of the selected route, word-wrapped, the
+AI-assisted parts marked the same way. Once you agree with them, `/overview apply` puts the suggestions
+into the route sources (`description` and `note` in YAML and XML, `.routeDescription(...)` and
+`.routeNote(...)` in Java); each changed file goes through the confirm dialog with its diff, whatever the
+`/write` mode. From then on they are part of the routes and no longer marked.
+
+With *AI Overview* set to *auto* in *F2 -> Settings*, the panel explains the project by itself when
+it opens and the summary is missing or out of date, once per project state. External AI agents get the
+same through the `camel_project_overview` and `camel_save_project_summary` tools; from the TUI's MCP
+server the summary they save goes through the confirm dialog too.
+
+Submitted prompts (including slash commands) participate in AI prompt history when
+`camel.tui.ai.promptHistory` is not `0`. Use *↑*/*↓* on the prompt line to recall them.
+
+Every answer ends with a byline saying what the question cost: the time it took, how many tools the
+model called and the time spent in them, the number of requests, the tokens and, with Ollama, how full
+the context window got (for example `61.1s · 25 tool calls, limit reached (2.5s in tools) · 26 requests
+· 231.3k tokens · ctx 18%`). The panel allows 25 tool calls per question. When the model reaches that
+the byline says `limit reached`, the panel asks the model to answer from what it has found so far, and
+the <<_ollama>> tab shows the question's request count in red with `limit` as its reason (the count is
+yellow from 10 requests, and the total time yellow from 30 seconds and orange from a minute). A question
+that runs into the limit is usually a tool that makes the model guess, not a weak model: the AI log
+shows which one.
+
+What the model says is checked like what it writes. A file goes through the validator before
+`camel_write_file` writes it; the answer shown in the chat is what you copy, so its simple expressions
+are checked against the catalog too: the `${...}` placeholders in the text and in Java or XML code
+blocks, and the `simple:` values and log messages of YAML blocks. A small model tends to put the
+operator inside the placeholder (`${header.user ?: 'Guest'}` instead of `${header.user} ?: 'Guest'`).
+When the check finds such an expression the panel sends the answer back to the model once, with what is
+wrong and the rule, and shows the corrected answer with `1 correction` in the byline. When the model
+does not fix it the answer is shown as it is with a *Simple check* line under it naming the expression
+and the error, and the AI log has the exchange. Placeholders that are not simple (a Maven
+`$\{camel-version}`, a shell variable) are left alone.
+
+Press *Ctrl+U* while the AI panel is open to toggle the AI Usage view. It shows token consumption from
+the embedded AI prompt (*TUI ask*) and from LLM calls made by the monitored integration (*integration*),
+the latter taken from OpenTelemetry GenAI spans when observability is enabled on the integration. The
+*Tokens per question* chart has one bar per question you asked, so a question that needed several tool
+calls shows as a single bar. The summary line splits the session time into *AI time* (waiting for the
+model) and *Tool time* (running the TUI tools the model called, with the number of calls), the summary line gives the
+average time per question (and per request in brackets), the model table has an *AVG/REQ* column with
+the average per request for that model, and the *Time per question* chart next to the token chart shows the
+two side by side for each question, so you can see whether a slow answer was the model or the tools.
+
+== AI log
+
+Every request the panel makes is recorded in the AI log (*F2* -> _AI & MCP_ -> _AI Log_, or the
+`tui_get_ai_log` tool): the question, each tool the model called with its arguments, the result with
+how long the tool took, and a `Response` line with the elapsed time and the token counts. When the
+model called tools, the elapsed time is broken down into the time spent waiting for the model and the
+time spent in tool calls (for example `5.2s, ai 4.1s, tools 1.1s/3`). The `Response` line
+also shows whether the provider reused its cached prompt. For Ollama it prints the prompt-processing
+(`prefill`) and generation (`gen`) time reported by the server -- a prefill of a fraction of a second
+on a 10k-token prompt means the cache was hit, while a prefill of several seconds means the whole
+prompt was processed again. For OpenAI, Anthropic and Gemini it prints the number of `cached` input
+tokens the provider reported. Use it to check that follow-up questions are cheap before blaming the
+model for being slow.
+
+== Ollama
+
+The Ollama tab (under More, in the *AI* group) shows how the model served by a local
+https://ollama.com[Ollama] is performing, in the spirit of an LLM dashboard. It works with or without a
+running integration: it finds Ollama at `localhost:11434`, at the address of `camel infra run ollama`,
+or at the endpoint the AI panel (*F8*) is using. The tab is listed only while an Ollama server answers;
+the TUI checks every ten seconds, so it appears shortly after `ollama serve` starts.
+
+* *Model* -- the loaded model with its family, parameters, quantization, layers, experts (and how many
+ are active per token for a mixture-of-experts model), how much of it sits in GPU memory, the
+ allocated context length and when Ollama will unload it. With no model loaded, the installed models
+ are listed instead.
+* *Throughput* -- decode and prefill tokens per second, *live* while the model is generating and
+ otherwise from the last request; time to first token and load time (a load of a second or more
+ is a cold start); session averages and a sparkline of the decode rate.
+* *Context* -- how full the context window is, the share of the prompt served from Ollama's cache,
+ whether the model is working or idle, the speculative decoding method in use, and a per-turn trend
+ of how much of the window each AI panel prompt filled, with the session peak and the compactions seen.
+* *Host* -- GPU utilization and memory (Apple silicon through `ioreg`, NVIDIA through `nvidia-smi`),
+ and CPU and memory of the Ollama server and its model runner.
+* *Requests* -- one line per question asked in the AI panel (a question with tool calls costs one
+ request per step; *Enter* unfolds the steps) with the question text, prompt and generated tokens,
+ cache hit, the share of the context window reached, prefill and decode tokens per second, time to
+ first token, the time you waited and the stop reason. Calls made by Camel routes are listed as
+ their own lines.
+
+Two kinds of requests appear in the log. Questions asked in the AI panel with Ollama as the provider
+come with the timings Ollama reports for each request (prompt evaluation, generation, model load,
+total). Calls made by Camel routes through `camel-langchain4j-chat`, `camel-openai` or
+`camel-spring-ai-chat` appear when the integration runs with GenAI observability (`--observe`, or
+`--dep=camel:ai-observability`), tagged with the route id; Camel records tokens and duration for those,
+not the phase split.
+
+The live figures, the context panel and the host panel need the model runner on the same machine:
+Ollama starts a `llama-server` process per loaded model and the tab reads its slot state a few times a
+second. Against a remote or containerised Ollama the tab keeps the model, per-request and session data
+and says which panels are unavailable.
+
+Press *r* to reset the request log and the session totals, *F5* to refresh immediately. The same data
+is available to AI agents through the `tui_get_ollama` MCP tool. For what the figures mean for the AI
+panel and which knobs to turn, see <<_working_with_a_local_ollama_model>>.
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-diagram.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-diagram.adoc
new file mode 100644
index 000000000000..d624c89f6c7f
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-diagram.adoc
@@ -0,0 +1,176 @@
+= Camel TUI Diagram
+
+The Diagram tab (*5*) draws your integration: the routes as boxes connected by the endpoints they share, with live
+message counts, from a business-level architecture view down to the processors of one route. It is the fastest way to
+understand an integration you did not write, and to see where the messages go and where they fail.
+
+See xref:camel-jbang-tui.adoc[Camel TUI] for getting started and the other pages.
+
+== Key Features
+
+* <<_diagram_levels,*Three levels*>> -- Architecture › Topology › Route, moved through with *v* or a click
+* <<_architecture_view,*Architecture view*>> -- the capabilities of the integration and how they connect
+* <<_topology_view,*Topology view*>> -- every route and the endpoints that connect them, with live counts
+* <<_drill_down_into_routes,*Drill-down*>> -- the processors of one route, step by step
+* <<_external_endpoints,*External endpoints*>> -- what the integration consumes from and sends to outside
+* <<_metrics_and_source_code,*Metrics and source*>> -- throughput and timing on the boxes, and the source a box comes from
+
+== Route Topology Diagram
+
+The Diagram tab renders the route topology as interactive ASCII art. It shows how routes
+connect to each other through shared endpoints (direct, seda, kafka, etc.).
+
+image::jbang/camel-tui-diagram.png[Diagram topology view]
+
+=== Topology View
+
+The topology shows all routes as boxes, connected by arrows:
+
+* *Trigger routes* (timer, cron, etc.) appear at the top
+* *Downstream routes* appear below, connected by directed arrows
+* Route boxes show the route ID, the `from` endpoint, and metrics when enabled
+
+Navigate between route boxes with arrow keys. When a route is selected, an *Info panel* appears
+on the left showing state, uptime, throughput, exchange counts, and processing times.
+
+image::jbang/camel-tui-diagram-topology.png[The topology of two routes: checkout calls payment-provider]
+
+=== Drill-Down into Routes
+
+Press *Enter* on a selected route to drill down into its internal EIP structure. Each processor
+and EIP node is displayed with its type (colored by category), endpoint URI, and per-node statistics.
+
+Nodes that connect to other routes show a *Enter* indicator -- press *Enter* to jump directly
+to the linked route. Navigation history is maintained as a breadcrumb stack: press *Esc* to go
+back to the previous route, and eventually back to the topology view.
+
+Press *t* to jump straight back to the topology from any depth.
+
+image::jbang/camel-tui-diagram-route.png[The checkout route drilled into, with the level bar on top]
+
+=== Diagram levels
+
+The Diagram tab shows one diagram at three zoom levels, and the line above it says which one you see:
+
+----
+ v ◇ Architecture › ◆ Topology › ◇ Route: order-intake b view: business g group ● m metrics ● e external ○
+----
+
+* *Architecture* -- the routes grouped by what they do for the business (see below);
+* *Topology* -- all the routes and how they connect; coming down from a capability, its routes are
+ highlighted, as the label says (`Topology · Order intake`);
+* *Route* -- the steps of one route.
+
+The level shown is highlighted; the others stay visible, and one that does not apply yet (Route,
+until a route is selected) is greyed out. *Enter* zooms in and *Esc* zooms out, from a route to its
+topology and from the topology to the architecture (at the architecture, *Esc* goes back to the Overview
+tab as on any tab). *v*, shown at the start of the line, moves to the next level and round again, and a
+click on a level goes there.
+
+The right side of the line holds the view settings of the level shown, with their state (● on, ○ off,
+or the mode). *a* ai, shown unless the AI Overview setting is off, switches every level between the view with the
+AI-assisted parts and the facts alone: off, the architecture groups only by what the sources say (route
+groups, shared services, utility, and Other for the rest), and the topology, the Info panel and the
+Routes tab show no AI label, note or group. It changes what is shown only: the AI overview setting, the
+summary and its automatic updates stay as they are. When the project has no `camel-summary.md` yet, *a*
+has the AI write one, as `/overview` does: the AI panel opens to show it start, and the diagram picks up
+the summary once it is saved. *b* switches every level between the *business* view and the *technical* view: route
+labels and what capabilities achieve (the AI-assisted parts marked ✦), or route ids with their
+endpoints and the entry points and systems of each capability. The business view is the default when
+the routes have descriptions, from their source or the AI project overview; *n*, the key of the former
+description toggle, does the same. *m* metrics and *e* external systems apply to the topology, *m* and
+*d* detail to a route. *g* group, in the topology, shows the architecture one level down: each route
+box names its group (a route group, an AI capability marked ✦, shared services or utility), each group
+has the border colour of its box in the architecture, and a legend at the bottom of the topology lists
+the groups in their colours; it is on when the project has groups. *u* shows or hides the utility
+routes, one setting for the architecture and the topology, so both show the same groups. The route
+boxes widen, within reason, so a label and its group fit on a line, and the Info panel of a route
+names its group (✦ when the AI placed it). The footer lists only actions, such as
+*Enter* drill-down, *c* source and *s* summary.
+
+=== Architecture View
+
+A topology of many routes turns into spaghetti. The Architecture level shows the
+routes grouped by what they do for the business, one box per group, so a project of eighty routes
+reads as a handful of boxes. The view reads the source files of the selected integration, not the
+running routes.
+
+Each route has one role:
+
+* *route group* -- the routes that set `group` in the source. The source always wins, and these
+ groups are drawn as facts, without a mark.
+* *capability* -- the business capabilities the xref:camel-jbang-tui-ai.adoc#_ai_project_overview[AI project overview]
+ proposed (`/overview` in the AI panel). An AI decided them, so they are drawn in the
+ `ai-assisted` style, italic with a `✦`.
+* *Shared services* -- routes that routes of two or more groups call or hand off to, such as an
+ audit or notification route. Derived from the links between routes, and shown once instead of in
+ every group that uses them.
+* *Utility* -- plumbing with little business meaning: a route reached only while handling a failure
+ (from a `doCatch`, an `onException` or a dead letter channel), a route that only logs, or one the
+ AI marked as utility. Hidden until you press *u*.
+* *Other* -- routes nothing above placed yet; `/overview` groups them.
+
+A box shows how many routes the group has, its entry points (HTTP, schedules, consumers) and the
+external systems its routes use; a warning count when the project overview found problems in its
+routes, such as a `direct` endpoint no route consumes. Arrows between boxes are the links between
+their routes, with the strongest kind (a call over a hand-off over an event). The Info panel on the
+left lists the routes, entry points, systems, and what the AI wrote about a capability.
+
+A small *Flow* panel at the bottom right shows the inside of the selected group, what *Enter* goes
+down to: each of its routes in the order messages flow, with where messages enter it and what it hands
+off to. That is the routes it links to (call, async, event, on error; a route of another group is named
+with its group, in that group's colour) and the remote systems it sends to, such as a queue or an HTTP
+service. Sends that stay inside the integration, such as a log, are left out, as the catalog says the
+component is not remote. It is not shown for an external system, whose Info panel lists its routes.
+
+Press *e* to draw the external systems as boxes of their own, dashed as in the topology: the systems
+messages come in from above the groups, the ones they go out to below, each linked to the groups that
+use it. A system only utility routes use goes away with them. Select a system to see in the Info panel
+which groups and routes use it and each of its endpoints with its route; *Enter* goes down to the
+topology with those routes highlighted. Press *e* again for the boxes alone.
+
+Press *Enter* on a box to go down to the topology of all routes, with that group's routes highlighted
+and the first of them selected, so you see the group in the whole picture of how the routes connect.
+*Esc* from there comes back to the architecture, on the group you came from. The view
+follows the project by itself: edited routes and a summary `/overview` has just written show up within a
+few seconds.
+
+`camel overview` prints the same grouping as the Architecture section of `camel-summary.md` (see
+xref:camel-jbang-ai.adoc#_project_overview[Project overview]).
+
+=== External Endpoints
+
+Press *e* to cycle through three modes for external endpoints:
+
+* *off* -- only route-to-route connections shown
+* *edges* -- external systems (kafka brokers, HTTP endpoints, databases) shown as dashed boxes
+* *all* -- routes sharing an external endpoint are connected through an intermediary box
+
+=== Metrics and Source Code
+
+* Press *m* to toggle metrics overlay (message counts on each node)
+* Press *c* to view the source code of the selected route, with syntax highlighting
+* Press *b* (or *n*) to switch between the business view (labels) and the technical view (route ids and endpoints)
+
+== Keyboard Shortcuts
+
+=== Diagram Tab
+
+[cols="2,5",options="header"]
+|===
+| Key | Action
+
+| *Arrow keys* | Navigate between route boxes (topology) or EIP nodes (drill-down)
+| *Enter* | Drill down into selected route / jump to linked route
+| *Esc* | Go back (previous route or topology)
+| *t* | Jump to topology view
+| *m* | Toggle metrics overlay
+| *e* | External systems: in the topology off, edges, all; in the architecture off or edges
+| *a* | AI-assisted parts shown, or the facts alone; without a `camel-summary.md` yet, has the AI write one
+| *b* (or *n*) | Business view (labels, what capabilities achieve) or technical view (route ids, endpoints)
+| *c* | View route source code
+| *v* | Next level: Architecture, Topology, Route
+| *u* | In the architecture and the topology: show or hide the utility routes
+| *g* | In the topology: show each route's group (route group, AI capability, shared services, utility)
+| *s* | Open the integration summary (`camel-summary.md`) in the document viewer, from any level
+|===
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-observe.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-observe.adoc
new file mode 100644
index 000000000000..78c044db9398
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-observe.adoc
@@ -0,0 +1,309 @@
+= Camel TUI Observing Integrations
+
+The TUI shows what a running integration is doing: every exchange as it happens, the full history of a message
+through the routes, the errors with their context, the traces, and the JVM underneath. This page covers the tabs for
+watching and troubleshooting an integration.
+
+See xref:camel-jbang-tui.adoc[Camel TUI] for getting started and the other pages.
+
+== Key Features
+
+* <<_activity,*Activity*>> -- live exchanges with their elapsed time, endpoint sends and failures
+* <<_message_insight,*Message insight*>> -- step through the history of an exchange, as a list, a waterfall or on the diagram
+* <<_troubleshooting_errors,*Errors*>> -- failures with the stack trace, the message and the path that led there
+* <<_opentelemetry_spans,*OpenTelemetry spans*>> -- the traces of the integration, without a tracing backend
+* <<_http_probe,*HTTP probe*>> -- call the HTTP endpoints of the integration from the TUI
+* <<_highlighted_features,*Deep dives*>> -- CVE audit, Kafka, SQL, memory leaks, JFR profiling and the catalog
+
+== Activity
+
+The Activity tab shows a live feed of exchange activity -- every exchange that flows through
+the system is captured with its route, status (OK or Failed), elapsed time, endpoint sends, and
+how long ago it completed.
+
+Activity data is captured when the integration runs in development mode (the `dev` profile), which is
+the default when running with `camel run`. Activity tracking can also be explicitly enabled via
+`camel.trace.activityEnabled=true` in `application.properties`. On a production profile without
+dev mode or explicit enablement, the tab is empty.
+
+The top panel shows aggregated statistics: total / OK / failed exchange counts, total sends,
+p50 / p95 / max elapsed times, and the time window of the visible entries.
+
+Select an exchange to see its details below: exchange ID, route, elapsed time, the remote endpoints
+called during the exchange with individual timings, and exception details if the exchange failed.
+
+Use *s* to cycle sort order, *S* to reverse, and *F5* to clear the activity list.
+
+== Message Insight
+
+The Inspect tab lets you step through an exchange processor by processor -- like
+scrubbing through a video timeline of your message's journey. This is the key to understanding
+what Camel does with your data at every step.
+
+image::jbang/camel-tui-inspect.png[Inspect tab showing message history and exchange details]
+
+=== History of Last Exchange
+
+When you open the Inspect tab, it shows the last completed exchange. The top panel lists
+every processing step with:
+
+* *Step number* and direction (--> or <--)
+* *Route* and *Node ID* of the processor
+* *BHPV* change indicators -- letters light up in yellow when Body, Headers, Properties,
+ or Variables changed at that step
+* *Elapsed* time per step
+
+Select a step with arrow keys, and the detail panel below shows the full exchange state:
+body content, headers, properties, and variables at that exact point in the processing chain.
+
+=== Controlling What You See
+
+Toggle sections of the detail view:
+
+* *b* -- show/hide message body
+* *h* -- show/hide headers
+* *p* -- show/hide exchange properties
+* *v* -- show/hide exchange variables
+* *w* -- toggle word wrap
+* *n* -- toggle description/processor labels
+
+=== Waterfall View
+
+Press *g* to switch to the waterfall view -- a horizontal bar chart showing how long each
+processor took. This makes it easy to spot bottlenecks: long bars stand out immediately.
+The selected step is highlighted with `>>` and processing times are color-coded from green
+(fast) to red (slow).
+
+image::jbang/camel-tui-observe-waterfall.png[The steps of an exchange as bars: the long ones show where the time went]
+
+=== Replay on the Diagram
+
+Press *d* to overlay the message path on the route topology diagram. This is where the
+timeline replay comes alive:
+
+* The diagram highlights which route and processor handled the message at each step
+* Use *Up/Down* arrows to step forward and backward through the path
+* An *Info panel* on the left shows the exchange state (body, headers, properties, variables)
+ at the current step -- values that changed from the previous step are highlighted in yellow
+* Step through the entire exchange to watch how the message payload transforms as it flows
+ through processors, filters, and content-based routers
+* Press *Enter* on a route node to drill down into its internal EIP structure while replaying
+* Press *Esc* to go back, *t* to return to the topology view
+* Press *i* to cycle the info panel size (narrow / wide / full)
+
+This is especially powerful for understanding complex multi-route flows where messages are
+routed through direct, seda, or kafka endpoints between routes.
+
+=== Live Tracing
+
+When you run your integration with tracing enabled:
+
+[source,bash]
+----
+camel run my-route.yaml --trace
+----
+
+The Inspect tab gains a live trace panel showing every exchange as it flows through the system.
+Each exchange is listed with its timestamp, starting route, status (Processing/Done/Failed),
+elapsed time, and step count. Press *Enter* to drill into an exchange and see every processor
+step -- the same step-by-step view and diagram replay work here too.
+
+Use *s* to cycle sort order (time, route, elapsed, exchange) and *S* to reverse.
+Press *F5* to clear captured traces.
+
+== Troubleshooting Errors
+
+The Errors tab collects failures with full stack traces and exchange context.
+When errors occur, a red badge appears on the tab.
+
+For deeper troubleshooting, press *d* on an error to see its Diagram view: the path the failed
+exchange took through the routes, replayed from its message history (the same replay as in the
+Inspect tab):
+
+* Failed steps are highlighted in red on the diagram
+* Step through the failing exchange to see the message state at each processor
+ leading up to the failure
+* The Info panel shows the exception message and which node threw it
+* Compare the message body and headers before and after the failing step
+ to understand what triggered the error
+
+This combination of error details + visual diagram replay gives you a complete picture of
+what went wrong and why -- without leaving the terminal.
+
+image::jbang/camel-tui-observe-error-diagram.png[A failed order: the path from checkout to payment-provider, and the onException handler that parked it]
+
+== OpenTelemetry Spans
+
+The Spans tab (under More, shortcut *o*) visualizes OpenTelemetry traces collected from your
+running integration. It shows every span with trace ID, span name, kind, status, duration,
+and Camel-specific context (route ID, processor ID).
+
+Run your integration with OpenTelemetry enabled:
+
+[source,bash]
+----
+camel run my-route.yaml --dep=camel:opentelemetry
+----
+
+Features:
+
+* *Waterfall view* -- spans displayed as a timeline showing parent-child relationships
+ and duration bars, color-coded from green (fast) to red (slow)
+* *Trace grouping* -- spans grouped by trace ID so you can follow a complete request
+ across multiple routes and components
+* *Camel-only filter* -- toggle to show only Camel-originated spans, hiding framework
+ and library spans
+* *Sort and search* -- sort by trace ID, route, status, duration, or span count;
+ filter with text search
+* *Error highlighting* -- failed spans (status ERROR) are highlighted in red
+
+This is especially useful for understanding latency in multi-route integrations and for
+correlating Camel processing with external service calls (HTTP, database, messaging).
+
+== Process Information
+
+The Process tab (under More, shortcut *p*) shows JVM process details for the selected
+integration: Java version, PID, uptime, command-line arguments, and system properties.
+
+== HTTP Probe
+
+The HTTP tab (under More > Routing > HTTP) lists all HTTP/REST endpoints in your integration.
+Press *Enter* on any endpoint to open the built-in HTTP probe -- a lightweight Postman for
+testing your REST services directly from the terminal.
+
+=== Probe Layout
+
+The probe screen is split into a request panel (left) and response panel (right):
+
+*Request panel* -- top to bottom:
+
+* *Method* -- HTTP verb cycler (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`).
+ Use *Left* / *Right* arrows to cycle.
+* *Path* -- editable path field, pre-filled from the endpoint. Supports `\{xxx\}` placeholders.
+* *Path Parameters* -- if the path contains `\{id\}`, `\{name\}`, etc., a fill-in field appears
+ for each placeholder. Values are substituted into the URL when sending.
+* *Query Parameters* -- key-value pairs appended to the URL as `?key=value&key2=value2`.
+ Press *+* to add a parameter.
+* *Content-Type* -- cycler with common MIME types (`application/json`, `application/xml`,
+ `text/plain`, etc.). Pre-filled from endpoint metadata when available.
+* *Accept* -- cycler for the Accept header. Pre-filled from endpoint metadata.
+* *Headers* -- custom request headers as key-value pairs. Press *+* to add a header.
+* *Body* -- multi-line text area (6 rows) for request body. Supports JSON, XML, plain text,
+ or `file:payload.json` to load from a file. Press *Enter* to insert newlines.
+* *History* -- previously sent requests with status codes and elapsed times. Press *Enter*
+ to replay a request, restoring all fields.
+
+*Response panel* -- shows the response body with status code, elapsed time, and response headers.
+Press *p* to toggle pretty-printing for JSON and XML responses.
+
+The resolved URL is shown at the top of the request panel as a clickable hyperlink that you
+can copy for use with `curl` or other tools.
+
+=== Sending Requests
+
+Press *F5* to send the request (same pattern as the SQL tab). The response appears in the
+right panel. While sending, the status shows a spinner.
+
+=== Keyboard Shortcuts (Probe)
+
+[cols="2,5",options="header"]
+|===
+| Key | Action
+
+| F5 | Send request
+| Enter | Insert newline (body) or advance to next field
+| Tab / Shift+Tab | Next / previous field
+| Left / Right | Cycle method, Content-Type, or Accept values
+| + | Add query parameter or header
+| Backspace | Remove empty query parameter or header
+| p | Toggle pretty-print response
+| Esc | Exit probe mode
+|===
+
+== Highlighted Features
+
+Beyond the core tabs described above, the TUI includes several specialized screens worth highlighting.
+
+=== CVE Audit
+
+The CVE Audit tab (under More > Project) scans all Maven dependencies on your integration's classpath
+against the https://osv.dev[OSV.dev] vulnerability database. It queries every JAR using the OSV batch
+API and displays known vulnerabilities grouped by severity (Critical, High, Medium, Low).
+
+Each vulnerability shows the CVE ID, affected artifact, the direct dependency that pulls it in (VIA column),
+and a summary. Select a CVE to see full details including CVSS vector, published date, fixed versions,
+and aliases. Results are cached globally -- switching integrations that share JARs is instant.
+
+=== Kafka
+
+The Kafka tab (under More > Data) provides a dedicated view for Kafka consumers and their connectivity
+status. It shows consumer group details, topic assignments, partition offsets, and reconnection state.
+When a broker connection drops, the Recovery Tasks tab shows the reconnection task with its
+Waiting/Attempting status, retry count, and error details.
+
+=== SQL Query and SQL Trace
+
+When your integration includes a DataSource, two SQL tabs appear under More > Data:
+
+* *SQL Query* -- an interactive SQL console where you can write and execute queries against any
+ DataSource in your integration. Results are displayed as a formatted table with column types.
+* *SQL Trace* -- captures and displays SQL statements executed by your routes in real-time,
+ showing query text, execution time, and the route that triggered them.
+
+=== Memory Leak Detection
+
+The Memory Leak tab (under More > JVM) uses Java Flight Recorder (JFR) to diagnose memory leaks
+in your running integration. It runs two sequential recordings and compares object retention trends,
+classifying each class as growing, stable, shrinking, new, or gone. This is lightweight and safe
+for production use.
+
+=== JFR Runtime Profiling
+
+The JFR tab (under More > Observability) gives you a lightweight profiling view of your running integration
+using Java Flight Recorder. JFR is built into the JVM with very low overhead, making it suitable
+for near-production use cases where you need timing data without impacting throughput.
+
+Start your integration with JFR runtime instrumentation enabled:
+
+[source,bash]
+----
+camel run my-route.yaml --jfr
+----
+
+The JFR tab shows the recording status and event configuration. Press *F5* to take a snapshot
+of the active recording -- the TUI aggregates all Camel events and presents them in five views:
+
+* *Routes* (key *1*) -- per-route totals, failure counts, and min/mean/max duration
+* *Processors* (key *2*) -- per-processor statistics with type and owning route, sorted by slowest first
+* *Endpoints* (key *3*) -- per-endpoint send statistics with duration
+* *Failures* (key *4*) -- recent exchange failures with exception type and message
+* *Redeliveries* (key *5*) -- recent redelivery attempts with attempt and max counts
+
+Press *Enter* on a route to drill down into its processors filtered by that route.
+Press *s* to cycle sort columns, and *Esc* to go back.
+
+Each snapshot is a point-in-time read -- the recording keeps running, so you can press *F5*
+again at any time to see updated statistics as more messages flow through the system.
+
+=== Catalog
+
+The Catalog tab (under More > Project) lets you browse the full Camel component catalog from within
+the TUI. Search for components by name, view their documentation, options, and supported headers --
+useful when building routes and you need to check what options a component supports.
+
+== Keyboard Shortcuts
+
+=== Inspect Tab
+
+[cols="2,5",options="header"]
+|===
+| Key | Action
+
+| *Up/Down* | Navigate between steps
+| *b* / *h* / *p* / *v* | Toggle body / headers / properties / variables
+| *w* | Toggle word wrap
+| *g* | Toggle waterfall view
+| *d* | Toggle diagram replay mode
+| *n* | Toggle description labels
+| *F5* | Refresh / clear traces
+|===
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-settings.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-settings.adoc
new file mode 100644
index 000000000000..96e3ab5bcba1
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-settings.adoc
@@ -0,0 +1,224 @@
+= Camel TUI Actions, Settings and Themes
+
+The TUI is configured from inside: the actions menu (*F2*) holds what is not tied to one tab, the settings are kept in
+`~/.camel-cli.properties`, and the themes change the whole look. This page also covers the embedded shell, opening the
+TUI in a browser, and recording demos.
+
+See xref:camel-jbang-tui.adoc[Camel TUI] for getting started and the other pages.
+
+== Key Features
+
+* <<_actions_menu_f2,*Actions menu*>> -- F2: settings, themes, send a message, the doctor, MCP info
+* <<_embedded_shell_f6,*Embedded shell*>> -- F6: run camel commands without leaving the TUI
+* <<_theme,*Themes*>> -- dark and light themes
+* <<_settings,*Settings*>> -- start tab, rate units, validation, AI provider and more
+* <<_web_browser_access,*Web browser access*>> -- the TUI in a browser tab
+* <<_recording_demos,*Recording demos*>> -- record a session as a tape and convert it to a GIF
+
+== Actions Menu (F2)
+
+Press *F2* to open the actions menu with quick access to common operations:
+
+[cols="2,5",options="header"]
+|===
+| Action | Description
+
+| Send Message | Send a test message to any route with custom body, headers, and exchange pattern.
+| Run an example... | Browse and launch built-in Camel examples from the catalog.
+| Open Project... | Open a project directory in the Source tab for browsing and editing. Run with F10.
+| Run from folder... | Run routes from a local directory.
+| Run Dev/Infra Service... | Start infrastructure services (Kafka, databases, etc.) in Docker.
+| Browse Files | Browse the integration's source files with syntax highlighting.
+| Run Doctor | Check your environment: Java version, JBang, Maven, Docker, port conflicts, disk space.
+| Reset Stats | Reset all statistics and metrics for the selected integration.
+| Stop All | Stop running integrations and/or infrastructure services.
+| Settings... | Change the theme, the starting tab, and the default run-from-folder.
+| Take Screenshot | Export the current screen as SVG, text, or ANSI art.
+| Start/Stop Tape Recording | Record your session as a `.tape` file for demos.
+| Quit | Quit the TUI, with the same confirmation as pressing *q*. The last entry of the menu, so quitting is one menu away on tabs and in input fields where *q* is taken by something else.
+|===
+
+=== Sending Test Messages
+
+Select *Send Message* from the F2 menu (or press *F2* then choose it):
+
+image::jbang/camel-tui-send.png[Send Message view with body editor and response area]
+
+* *Choose the route* -- use left/right arrows to pick the target route
+* *Enter the body* -- type the message body, or use `file:path/to/file` to load from a file
+* *Add headers* -- press *+* to add headers as key=value pairs
+* *Set exchange pattern* -- toggle between InOnly (fire-and-forget) and InOut (request/reply)
+* Press *Enter* to send
+
+For InOut exchanges, the response is displayed below with status, elapsed time, response headers,
+and body. Press *P* to toggle pretty-printing for JSON/XML responses.
+
+=== Doctor
+
+The Doctor checks your development environment and reports issues:
+
+* Java version (17+ required, 21+ recommended)
+* Camel catalog availability
+* JBang installation
+* Maven repository connectivity
+* Docker/Podman availability
+* Common port conflicts (8080, 8443, 9090)
+* Disk space in temp directory
+
+== Embedded Shell (F6)
+
+Press *F6* to open an embedded Camel JBang shell at the bottom (or top) of the screen. Any `camel`
+command can be run there -- `camel run`, `camel infra run kafka`, `camel cmd send`, `camel get` and
+so on -- without leaving the dashboard, and the tabs keep updating while the command runs. Press
+*F6* again to close the panel, *Shift+F6* to cycle its height, *PgUp*/*PgDn* to scroll the output
+and *↑*/*↓* to recall earlier commands (see <<_input_history>>).
+
+The shell and the AI prompt panel (*F8*) share the same space: opening one closes the other. Both
+open at the bottom by default; see *Panel Position* in <<_settings>>.
+
+== Theme
+
+The TUI ships with 21 color themes defined as CSS stylesheets:
+
+* *Dark themes* -- Dark (default), Dracula, Nord, Solarized Dark, Gruvbox Dark,
+ Catppuccin Mocha, Catppuccin Frappé, Tokyo Night, Rosé Pine, Rosé Pine Moon, Kanagawa,
+ Everforest, Monochrome, CRT, Turbo Pascal
+* *Light themes* -- Light, Nord Light, Solarized Light, Gruvbox Light, Catppuccin Latte,
+ Everforest Light
+
+Open the *F2* actions menu and choose *Settings...* to switch themes, or pass
+`--theme=<name>` on the command line (e.g., `--theme=tokyo-night`). The CLI value
+overrides the persisted preference from `.camel-cli.properties`; runtime toggles and
+the config file still apply on later launches when `--theme` is omitted.
+
+The brand orange accent is consistent across most themes; status colors (success,
+warning, error) and borders adapt for readability on each palette. A few themes trade
+the brand accent for their own identity: Monochrome, CRT and Turbo Pascal. The Turbo
+Pascal theme recreates Borland's IDE (yellow text on the blue editor field, cyan window
+frames, grey menu bar) and also restyles source code the way that editor did: reserved
+words in white, code in yellow, comments in grey. Other themes highlight code with a
+fixed Monokai (dark) or GitHub-inspired (light) palette.
+
+Your choice is remembered: it is saved as `camel.tui.theme` in `.camel-cli.properties`
+and restored the next time you open the TUI.
+
+image::jbang/camel-tui-theme-latte.png[The Overview in the Catppuccin Latte theme]
+
+== Settings
+
+Open the *F2* actions menu and choose *Settings...* to change TUI preferences in one place:
+
+* *Theme* -- cycle through 21 available themes (applied immediately on save).
+* *Starting Tab* -- the tab shown when the TUI launches; any tab (primary or under *More*) can be
+ chosen. Defaults to *Overview*.
+* *Select Tab* -- the tab to switch to when selecting an integration from the Overview tab.
+ Defaults to *Log*.
+* *Confirm* -- whether destructive actions (quit, stop, restart, stop/start routes) show a
+ confirmation dialog before executing. Defaults to *on*. Kill (*X*) always confirms regardless
+ of this setting.
+* *Default Folder* -- the folder pre-filled in *Run from Folder*. The most recently used folder
+ still takes precedence; this default is used only when there is no remembered folder.
+* *Panel Position* -- where the shell (*F6*) and AI (*F8*) panels open: *bottom* (default) or
+ *top*.
+* *Panel Space* -- whether those panels push the tab content aside (*move*, default) or are drawn
+ on top of it (*overlay*), so the tab keeps its full height underneath.
+* *AI Overview* -- the xref:camel-jbang-tui-ai.adoc#_ai_project_overview[AI project overview]: *manual* (default, only with
+ `/overview`), *auto* (also when the AI panel opens and the project summary is missing or out of
+ date), or *off* (no `/overview`, and no AI-assisted descriptions in the tabs).
+
+Use *↑*/*↓* to move between rows, *Space* (or *←*/*→*) to cycle the theme and tab settings, type to
+edit the default folder, *Enter* to save, and *Esc* to cancel.
+
+Settings are stored under `camel.tui.*` keys (`camel.tui.theme`, `camel.tui.startTab`,
+`camel.tui.selectTab`, `camel.tui.confirmActions`, `camel.tui.defaultFolder`,
+`camel.tui.panelPosition`, `camel.tui.panelSpace`,
+`camel.tui.shell.history`, `camel.tui.ai.provider`, `camel.tui.ai.model`, `camel.tui.ai.url`,
+`camel.tui.ai.tools`, `camel.tui.ai.overview`, `camel.tui.ai.promptHistory`) in the Camel CLI configuration file. Each key is read from and
+written back to the file where it currently lives: a key present in the local
+`./camel-cli.properties` is treated as a project-level override and stays local, while every
+other key defaults to the global `~/.camel-cli.properties`. This means a project can
+deliberately pin a starting tab in its local config without redirecting your personal theme
+into the project file. See xref:camel-jbang-configuration.adoc[Configuration] for details
+on the global and local files.
+
+=== Input history
+
+The embedded shell (*F6*) and AI prompt (*F8*) keep a recall list for the command line and prompt
+respectively. Use *↑*/*↓* on the input line to walk previous entries. Limits are configured with
+`camel.tui.shell.history` and `camel.tui.ai.promptHistory` in `.camel-cli.properties` (default
+`100` each; set to `0` to disable recall and persistence). Shell history is stored in
+`~/.camel/tui-shell.history`; AI prompt history in `~/.camel/tui-ai-prompt.history`.
+
+=== Pasting
+
+Both panels accept text pasted from the terminal (for example a model name such as
+`qwen3.6:35b-a3b` after `/model`). In the AI prompt, line breaks in the pasted text are collapsed
+to spaces so the paste stays a single prompt you can review before pressing *Enter*. In the shell,
+line breaks are sent as *Enter*, so a multi-line paste runs line by line as in a regular terminal.
+
+== Web Browser Access
+
+The TUI can also be reached from a web browser on the same host, using the same dashboard you'd see in a
+local terminal -- useful when you prefer a browser session to a terminal window.
+
+[source,bash]
+----
+camel tui --web
+----
+
+This starts a web terminal server on `localhost:8090` (configurable with `--web-port`).
+Open `http://localhost:8090` in a browser to get a full xterm.js terminal driving the same
+TUI dashboard, with the same tabs, keyboard shortcuts, and F2 actions menu as a local session.
+
+Like the MCP server, the web server is bound to `127.0.0.1` only -- it never listens on
+external interfaces -- and there is no authentication beyond that. Each browser connection
+gets its own independent TUI session (its own process discovery and navigation state), the
+same as if you'd run `camel tui` again in a new terminal.
+
+== Recording Demos
+
+The TUI can record terminal sessions for demos and documentation.
+
+=== Live Recording
+
+Use the *F2* actions menu and select *Start Tape Recording* to start recording your session
+as a `.tape` file. Select *Stop Tape Recording* to stop. The tape captures your keystrokes
+with timing, producing a script that can be replayed or converted to an animated GIF.
+
+=== Scripted Recording
+
+Use the `--record` flag to replay a `.tape` file in headless mode and produce an
+https://asciinema.org/[Asciinema] `.cast` recording:
+
+[source,bash]
+----
+camel tui --record=demo.tape
+----
+
+The `.cast` file is written next to the tape, with the `.tape` suffix replaced by `.cast`.
+Recording is headless: the TUI is driven entirely by the tape rather than by your terminal,
+so no keyboard input is read and nothing is drawn on screen.
+
+The recorded terminal is 200x50 by default, which is wider than a documentation page can
+display. Use `--record-size` to record at a size that fits, and `--record-fps` or
+`--record-duration` to control the capture rate and the cut-off:
+
+[source,bash]
+----
+camel tui --record=demo.tape --record-size=160x44 --record-fps=15
+----
+
+`--record` cannot be combined with `--web`. Recording drives a headless TUI from the tape, and
+the recording configuration applies to the whole process, so every browser session would be
+recorded into the same `.cast` file. Camel rejects the combination with an error instead.
+
+=== Converting to GIF
+
+Convert recordings using https://github.com/asciinema/agg[agg] (for `.cast` files) or
+https://github.com/charmbracelet/vhs[VHS] (for `.tape` files):
+
+[source,bash]
+----
+agg recording.cast out.gif # .cast -> .gif
+vhs demo.tape # .tape -> .gif
+----
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
index e3e6f56e4014..cb1ec9113de0 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui-source-editor.adoc
@@ -101,10 +101,10 @@ image::jbang/camel-tui-source-ai-edit-confirm.png[The change of the AI waits for
A file the AI writes is checked like one you save, and a write that brings new problems is refused, so the AI gets the
problems back and can try again. The view shows the file as the AI wrote it as soon as you apply the change. With `/write live` in the AI panel, you can also watch the AI type its change in the
-editor; see xref:camel-jbang-tui.adoc#_watching_the_ai_edit_live_mode[Watching the AI edit].
+editor; see xref:camel-jbang-tui-ai-agents.adoc#_watching_the_ai_edit_live_mode[Watching the AI edit].
The AI panel works with a hosted provider or with a local model through Ollama; see
-xref:camel-jbang-tui.adoc#_choosing_an_ai_provider[Choosing an AI provider].
+xref:camel-jbang-tui-ai.adoc#_choosing_an_ai_provider[Choosing an AI provider].
== Completion
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
index ed242f440dc7..71a2c91b5205 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
@@ -11,6 +11,21 @@ does with your routes. No more black box.
image::jbang/camel-tui-overview.png[TUI Overview showing multiple routes]
+== Key Features
+
+* *Run anything* -- your own routes, the built-in examples, or an existing Spring Boot or Quarkus project
+ (<<_getting_started,Getting started>>).
+* *Write routes with help* -- a xref:camel-jbang-tui-source-editor.adoc[source editor] that checks YAML, Java and XML
+ routes as you type, completes endpoint options, fixes problems and shows the live run data of each line.
+* *See the integration* -- the xref:camel-jbang-tui-diagram.adoc[diagram] from the architecture down to one route,
+ with live message counts.
+* *Watch and troubleshoot* -- xref:camel-jbang-tui-observe.adoc[live activity, message history, errors, traces], and
+ deep dives into Kafka, SQL, memory leaks, JFR and CVEs.
+* *Ask the AI* -- the xref:camel-jbang-tui-ai.adoc[AI panel] (*F8*) with a hosted or a local model, and
+ xref:camel-jbang-tui-ai-agents.adoc[AI coding agents] that see and drive the TUI over MCP and ACP.
+* *Make it yours* -- xref:camel-jbang-tui-settings.adoc[themes, settings], the embedded shell, browser access and demo
+ recording.
+
== Getting Started
You can start using the TUI in two ways: with your own route, or by running one of the built-in examples.
@@ -88,6 +103,8 @@ shows its logs.
This is a quick way to explore and run any Camel project without starting it separately first.
+image::jbang/camel-tui-main-quarkus-source.png[A Quarkus project in the Source tab: its Java route and the bean of the line]
+
=== Connecting Existing Spring Boot and Quarkus Applications
The TUI auto-discovers integrations started with `camel run`. To monitor and control
@@ -163,8 +180,8 @@ classpath. The TUI adapts to show only what's relevant to your integration.
Tab badges show live counts -- the Errors tab shows a red badge when errors exist
and Routes shows the route count.
-Two panels can be opened on top of any tab: *F6* opens an <<_embedded_shell_f6,embedded shell>>
-for running `camel` commands, and *F8* opens the <<_ai_integration_mcp,AI prompt>> for asking
+Two panels can be opened on top of any tab: *F6* opens an xref:camel-jbang-tui-settings.adoc#_embedded_shell_f6[embedded shell]
+for running `camel` commands, and *F8* opens the xref:camel-jbang-tui-ai.adoc[AI panel] for asking
questions about the running integrations.
== Source Code Browser
@@ -178,520 +195,24 @@ image::jbang/camel-tui-source-live-run-data.png[Live run data in the source edit
See xref:camel-jbang-tui-source-editor.adoc[Camel TUI Source Editor] for all its features and keys.
-== Activity
-
-The Activity tab shows a live feed of exchange activity -- every exchange that flows through
-the system is captured with its route, status (OK or Failed), elapsed time, endpoint sends, and
-how long ago it completed.
-
-Activity data is captured when the integration runs in development mode (the `dev` profile), which is
-the default when running with `camel run`. Activity tracking can also be explicitly enabled via
-`camel.trace.activityEnabled=true` in `application.properties`. On a production profile without
-dev mode or explicit enablement, the tab is empty.
-
-The top panel shows aggregated statistics: total / OK / failed exchange counts, total sends,
-p50 / p95 / max elapsed times, and the time window of the visible entries.
-
-Select an exchange to see its details below: exchange ID, route, elapsed time, the remote endpoints
-called during the exchange with individual timings, and exception details if the exchange failed.
-
-Use *s* to cycle sort order, *S* to reverse, and *F5* to clear the activity list.
-
-== Route Topology Diagram
-
-The Diagram tab renders the route topology as interactive ASCII art. It shows how routes
-connect to each other through shared endpoints (direct, seda, kafka, etc.).
-
-image::jbang/camel-tui-diagram.png[Diagram topology view]
-
-=== Topology View
-
-The topology shows all routes as boxes, connected by arrows:
-
-* *Trigger routes* (timer, cron, etc.) appear at the top
-* *Downstream routes* appear below, connected by directed arrows
-* Route boxes show the route ID, the `from` endpoint, and metrics when enabled
-
-Navigate between route boxes with arrow keys. When a route is selected, an *Info panel* appears
-on the left showing state, uptime, throughput, exchange counts, and processing times.
-
-=== Drill-Down into Routes
-
-Press *Enter* on a selected route to drill down into its internal EIP structure. Each processor
-and EIP node is displayed with its type (colored by category), endpoint URI, and per-node statistics.
-
-Nodes that connect to other routes show a *Enter* indicator -- press *Enter* to jump directly
-to the linked route. Navigation history is maintained as a breadcrumb stack: press *Esc* to go
-back to the previous route, and eventually back to the topology view.
-
-Press *t* to jump straight back to the topology from any depth.
-
-=== Diagram levels
-
-The Diagram tab shows one diagram at three zoom levels, and the line above it says which one you see:
-
-----
- v ◇ Architecture › ◆ Topology › ◇ Route: order-intake b view: business g group ● m metrics ● e external ○
-----
-
-* *Architecture* -- the routes grouped by what they do for the business (see below);
-* *Topology* -- all the routes and how they connect; coming down from a capability, its routes are
- highlighted, as the label says (`Topology · Order intake`);
-* *Route* -- the steps of one route.
-
-The level shown is highlighted; the others stay visible, and one that does not apply yet (Route,
-until a route is selected) is greyed out. *Enter* zooms in and *Esc* zooms out, from a route to its
-topology and from the topology to the architecture (at the architecture, *Esc* goes back to the Overview
-tab as on any tab). *v*, shown at the start of the line, moves to the next level and round again, and a
-click on a level goes there.
-
-The right side of the line holds the view settings of the level shown, with their state (● on, ○ off,
-or the mode). *a* ai, shown unless the AI Overview setting is off, switches every level between the view with the
-AI-assisted parts and the facts alone: off, the architecture groups only by what the sources say (route
-groups, shared services, utility, and Other for the rest), and the topology, the Info panel and the
-Routes tab show no AI label, note or group. It changes what is shown only: the AI overview setting, the
-summary and its automatic updates stay as they are. When the project has no `camel-summary.md` yet, *a*
-has the AI write one, as `/overview` does: the AI panel opens to show it start, and the diagram picks up
-the summary once it is saved. *b* switches every level between the *business* view and the *technical* view: route
-labels and what capabilities achieve (the AI-assisted parts marked ✦), or route ids with their
-endpoints and the entry points and systems of each capability. The business view is the default when
-the routes have descriptions, from their source or the AI project overview; *n*, the key of the former
-description toggle, does the same. *m* metrics and *e* external systems apply to the topology, *m* and
-*d* detail to a route. *g* group, in the topology, shows the architecture one level down: each route
-box names its group (a route group, an AI capability marked ✦, shared services or utility), each group
-has the border colour of its box in the architecture, and a legend at the bottom of the topology lists
-the groups in their colours; it is on when the project has groups. *u* shows or hides the utility
-routes, one setting for the architecture and the topology, so both show the same groups. The route
-boxes widen, within reason, so a label and its group fit on a line, and the Info panel of a route
-names its group (✦ when the AI placed it). The footer lists only actions, such as
-*Enter* drill-down, *c* source and *s* summary.
-
-=== Architecture View
-
-A topology of many routes turns into spaghetti. The Architecture level shows the
-routes grouped by what they do for the business, one box per group, so a project of eighty routes
-reads as a handful of boxes. The view reads the source files of the selected integration, not the
-running routes.
-
-Each route has one role:
-
-* *route group* -- the routes that set `group` in the source. The source always wins, and these
- groups are drawn as facts, without a mark.
-* *capability* -- the business capabilities the <<_ai_project_overview,AI project overview>>
- proposed (`/overview` in the AI panel). An AI decided them, so they are drawn in the
- `ai-assisted` style, italic with a `✦`.
-* *Shared services* -- routes that routes of two or more groups call or hand off to, such as an
- audit or notification route. Derived from the links between routes, and shown once instead of in
- every group that uses them.
-* *Utility* -- plumbing with little business meaning: a route reached only while handling a failure
- (from a `doCatch`, an `onException` or a dead letter channel), a route that only logs, or one the
- AI marked as utility. Hidden until you press *u*.
-* *Other* -- routes nothing above placed yet; `/overview` groups them.
-
-A box shows how many routes the group has, its entry points (HTTP, schedules, consumers) and the
-external systems its routes use; a warning count when the project overview found problems in its
-routes, such as a `direct` endpoint no route consumes. Arrows between boxes are the links between
-their routes, with the strongest kind (a call over a hand-off over an event). The Info panel on the
-left lists the routes, entry points, systems, and what the AI wrote about a capability.
-
-A small *Flow* panel at the bottom right shows the inside of the selected group, what *Enter* goes
-down to: each of its routes in the order messages flow, with where messages enter it and what it hands
-off to. That is the routes it links to (call, async, event, on error; a route of another group is named
-with its group, in that group's colour) and the remote systems it sends to, such as a queue or an HTTP
-service. Sends that stay inside the integration, such as a log, are left out, as the catalog says the
-component is not remote. It is not shown for an external system, whose Info panel lists its routes.
-
-Press *e* to draw the external systems as boxes of their own, dashed as in the topology: the systems
-messages come in from above the groups, the ones they go out to below, each linked to the groups that
-use it. A system only utility routes use goes away with them. Select a system to see in the Info panel
-which groups and routes use it and each of its endpoints with its route; *Enter* goes down to the
-topology with those routes highlighted. Press *e* again for the boxes alone.
-
-Press *Enter* on a box to go down to the topology of all routes, with that group's routes highlighted
-and the first of them selected, so you see the group in the whole picture of how the routes connect.
-*Esc* from there comes back to the architecture, on the group you came from. The view
-follows the project by itself: edited routes and a summary `/overview` has just written show up within a
-few seconds.
-
-`camel overview` prints the same grouping as the Architecture section of `camel-summary.md` (see
-xref:camel-jbang-ai.adoc#_project_overview[Project overview]).
-
-=== External Endpoints
-
-Press *e* to cycle through three modes for external endpoints:
-
-* *off* -- only route-to-route connections shown
-* *edges* -- external systems (kafka brokers, HTTP endpoints, databases) shown as dashed boxes
-* *all* -- routes sharing an external endpoint are connected through an intermediary box
-
-=== Metrics and Source Code
-
-* Press *m* to toggle metrics overlay (message counts on each node)
-* Press *c* to view the source code of the selected route, with syntax highlighting
-* Press *b* (or *n*) to switch between the business view (labels) and the technical view (route ids and endpoints)
-
-== Message Insight
-
-The Inspect tab lets you step through an exchange processor by processor -- like
-scrubbing through a video timeline of your message's journey. This is the key to understanding
-what Camel does with your data at every step.
-
-image::jbang/camel-tui-inspect.png[Inspect tab showing message history and exchange details]
-
-=== History of Last Exchange
-
-When you open the Inspect tab, it shows the last completed exchange. The top panel lists
-every processing step with:
-
-* *Step number* and direction (--> or <--)
-* *Route* and *Node ID* of the processor
-* *BHPV* change indicators -- letters light up in yellow when Body, Headers, Properties,
- or Variables changed at that step
-* *Elapsed* time per step
-
-Select a step with arrow keys, and the detail panel below shows the full exchange state:
-body content, headers, properties, and variables at that exact point in the processing chain.
-
-=== Controlling What You See
-
-Toggle sections of the detail view:
-
-* *b* -- show/hide message body
-* *h* -- show/hide headers
-* *p* -- show/hide exchange properties
-* *v* -- show/hide exchange variables
-* *w* -- toggle word wrap
-* *n* -- toggle description/processor labels
-
-=== Waterfall View
-
-Press *g* to switch to the waterfall view -- a horizontal bar chart showing how long each
-processor took. This makes it easy to spot bottlenecks: long bars stand out immediately.
-The selected step is highlighted with `>>` and processing times are color-coded from green
-(fast) to red (slow).
-
-=== Replay on the Diagram
-
-Press *d* to overlay the message path on the route topology diagram. This is where the
-timeline replay comes alive:
-
-* The diagram highlights which route and processor handled the message at each step
-* Use *Up/Down* arrows to step forward and backward through the path
-* An *Info panel* on the left shows the exchange state (body, headers, properties, variables)
- at the current step -- values that changed from the previous step are highlighted in yellow
-* Step through the entire exchange to watch how the message payload transforms as it flows
- through processors, filters, and content-based routers
-* Press *Enter* on a route node to drill down into its internal EIP structure while replaying
-* Press *Esc* to go back, *t* to return to the topology view
-* Press *i* to cycle the info panel size (narrow / wide / full)
-
-This is especially powerful for understanding complex multi-route flows where messages are
-routed through direct, seda, or kafka endpoints between routes.
-
-=== Live Tracing
-
-When you run your integration with tracing enabled:
-
-[source,bash]
-----
-camel run my-route.yaml --trace
-----
-
-The Inspect tab gains a live trace panel showing every exchange as it flows through the system.
-Each exchange is listed with its timestamp, starting route, status (Processing/Done/Failed),
-elapsed time, and step count. Press *Enter* to drill into an exchange and see every processor
-step -- the same step-by-step view and diagram replay work here too.
-
-Use *s* to cycle sort order (time, route, elapsed, exchange) and *S* to reverse.
-Press *F5* to clear captured traces.
-
-== Troubleshooting Errors
-
-The Errors tab collects failures with full stack traces and exchange context.
-When errors occur, a red badge appears on the tab.
-
-For deeper troubleshooting, switch to the Inspect tab and use the diagram replay
-(press *d*) to visualize exactly where the failure occurred:
-
-* Failed steps are highlighted in red on the diagram
-* Step through the failing exchange to see the message state at each processor
- leading up to the failure
-* The Info panel shows the exception message and which node threw it
-* Compare the message body and headers before and after the failing step
- to understand what triggered the error
-
-This combination of error details + visual diagram replay gives you a complete picture of
-what went wrong and why -- without leaving the terminal.
-
-== OpenTelemetry Spans
-
-The Spans tab (under More, shortcut *o*) visualizes OpenTelemetry traces collected from your
-running integration. It shows every span with trace ID, span name, kind, status, duration,
-and Camel-specific context (route ID, processor ID).
-
-Run your integration with OpenTelemetry enabled:
-
-[source,bash]
-----
-camel run my-route.yaml --dep=camel:opentelemetry
-----
-
-Features:
-
-* *Waterfall view* -- spans displayed as a timeline showing parent-child relationships
- and duration bars, color-coded from green (fast) to red (slow)
-* *Trace grouping* -- spans grouped by trace ID so you can follow a complete request
- across multiple routes and components
-* *Camel-only filter* -- toggle to show only Camel-originated spans, hiding framework
- and library spans
-* *Sort and search* -- sort by trace ID, route, status, duration, or span count;
- filter with text search
-* *Error highlighting* -- failed spans (status ERROR) are highlighted in red
-
-This is especially useful for understanding latency in multi-route integrations and for
-correlating Camel processing with external service calls (HTTP, database, messaging).
-
-== Ollama
-
-The Ollama tab (under More, in the *AI* group) shows how the model served by a local
-https://ollama.com[Ollama] is performing, in the spirit of an LLM dashboard. It works with or without a
-running integration: it finds Ollama at `localhost:11434`, at the address of `camel infra run ollama`,
-or at the endpoint the AI panel (*F8*) is using. The tab is listed only while an Ollama server answers;
-the TUI checks every ten seconds, so it appears shortly after `ollama serve` starts.
-
-* *Model* -- the loaded model with its family, parameters, quantization, layers, experts (and how many
- are active per token for a mixture-of-experts model), how much of it sits in GPU memory, the
- allocated context length and when Ollama will unload it. With no model loaded, the installed models
- are listed instead.
-* *Throughput* -- decode and prefill tokens per second, *live* while the model is generating and
- otherwise from the last request; time to first token and load time (a load of a second or more
- is a cold start); session averages and a sparkline of the decode rate.
-* *Context* -- how full the context window is, the share of the prompt served from Ollama's cache,
- whether the model is working or idle, the speculative decoding method in use, and a per-turn trend
- of how much of the window each AI panel prompt filled, with the session peak and the compactions seen.
-* *Host* -- GPU utilization and memory (Apple silicon through `ioreg`, NVIDIA through `nvidia-smi`),
- and CPU and memory of the Ollama server and its model runner.
-* *Requests* -- one line per question asked in the AI panel (a question with tool calls costs one
- request per step; *Enter* unfolds the steps) with the question text, prompt and generated tokens,
- cache hit, the share of the context window reached, prefill and decode tokens per second, time to
- first token, the time you waited and the stop reason. Calls made by Camel routes are listed as
- their own lines.
-
-Two kinds of requests appear in the log. Questions asked in the AI panel with Ollama as the provider
-come with the timings Ollama reports for each request (prompt evaluation, generation, model load,
-total). Calls made by Camel routes through `camel-langchain4j-chat`, `camel-openai` or
-`camel-spring-ai-chat` appear when the integration runs with GenAI observability (`--observe`, or
-`--dep=camel:ai-observability`), tagged with the route id; Camel records tokens and duration for those,
-not the phase split.
-
-The live figures, the context panel and the host panel need the model runner on the same machine:
-Ollama starts a `llama-server` process per loaded model and the tab reads its slot state a few times a
-second. Against a remote or containerised Ollama the tab keeps the model, per-request and session data
-and says which panels are unavailable.
-
-Press *r* to reset the request log and the session totals, *F5* to refresh immediately. The same data
-is available to AI agents through the `tui_get_ollama` MCP tool. For what the figures mean for the AI
-panel and which knobs to turn, see <<_working_with_a_local_ollama_model>>.
-
-== Process Information
-
-The Process tab (under More, shortcut *p*) shows JVM process details for the selected
-integration: Java version, PID, uptime, command-line arguments, and system properties.
-
-== HTTP Probe
-
-The HTTP tab (under More > Routing > HTTP) lists all HTTP/REST endpoints in your integration.
-Press *Enter* on any endpoint to open the built-in HTTP probe -- a lightweight Postman for
-testing your REST services directly from the terminal.
-
-=== Probe Layout
-
-The probe screen is split into a request panel (left) and response panel (right):
-
-*Request panel* -- top to bottom:
-
-* *Method* -- HTTP verb cycler (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`).
- Use *Left* / *Right* arrows to cycle.
-* *Path* -- editable path field, pre-filled from the endpoint. Supports `\{xxx\}` placeholders.
-* *Path Parameters* -- if the path contains `\{id\}`, `\{name\}`, etc., a fill-in field appears
- for each placeholder. Values are substituted into the URL when sending.
-* *Query Parameters* -- key-value pairs appended to the URL as `?key=value&key2=value2`.
- Press *+* to add a parameter.
-* *Content-Type* -- cycler with common MIME types (`application/json`, `application/xml`,
- `text/plain`, etc.). Pre-filled from endpoint metadata when available.
-* *Accept* -- cycler for the Accept header. Pre-filled from endpoint metadata.
-* *Headers* -- custom request headers as key-value pairs. Press *+* to add a header.
-* *Body* -- multi-line text area (6 rows) for request body. Supports JSON, XML, plain text,
- or `file:payload.json` to load from a file. Press *Enter* to insert newlines.
-* *History* -- previously sent requests with status codes and elapsed times. Press *Enter*
- to replay a request, restoring all fields.
-
-*Response panel* -- shows the response body with status code, elapsed time, and response headers.
-Press *p* to toggle pretty-printing for JSON and XML responses.
-
-The resolved URL is shown at the top of the request panel as a clickable hyperlink that you
-can copy for use with `curl` or other tools.
-
-=== Sending Requests
-
-Press *F5* to send the request (same pattern as the SQL tab). The response appears in the
-right panel. While sending, the status shows a spinner.
-
-=== Keyboard Shortcuts (Probe)
-
-[cols="2,5",options="header"]
-|===
-| Key | Action
-
-| F5 | Send request
-| Enter | Insert newline (body) or advance to next field
-| Tab / Shift+Tab | Next / previous field
-| Left / Right | Cycle method, Content-Type, or Accept values
-| + | Add query parameter or header
-| Backspace | Remove empty query parameter or header
-| p | Toggle pretty-print response
-| Esc | Exit probe mode
-|===
-
-== Actions Menu (F2)
-
-Press *F2* to open the actions menu with quick access to common operations:
+== More about the TUI
-[cols="2,5",options="header"]
+[cols="1,3",options="header"]
|===
-| Action | Description
-
-| Send Message | Send a test message to any route with custom body, headers, and exchange pattern.
-| Run an example... | Browse and launch built-in Camel examples from the catalog.
-| Open Project... | Open a project directory in the Source tab for browsing and editing. Run with F10.
-| Run from folder... | Run routes from a local directory.
-| Run Dev/Infra Service... | Start infrastructure services (Kafka, databases, etc.) in Docker.
-| Browse Files | Browse the integration's source files with syntax highlighting.
-| Run Doctor | Check your environment: Java version, JBang, Maven, Docker, port conflicts, disk space.
-| Reset Stats | Reset all statistics and metrics for the selected integration.
-| Stop All | Stop running integrations and/or infrastructure services.
-| Settings... | Change the theme, the starting tab, and the default run-from-folder.
-| Take Screenshot | Export the current screen as SVG, text, or ANSI art.
-| Start/Stop Tape Recording | Record your session as a `.tape` file for demos.
-| Quit | Quit the TUI, with the same confirmation as pressing *q*. The last entry of the menu, so quitting is one menu away on tabs and in input fields where *q* is taken by something else.
+| Page | What it covers
+
+| xref:camel-jbang-tui-source-editor.adoc[Source Editor] | Reading and writing routes: checks as you type, quick fixes,
+fix with AI, completion, quick documentation, navigation, live run data
+| xref:camel-jbang-tui-diagram.adoc[Diagram] | The architecture, topology and route views, external endpoints, metrics
+| xref:camel-jbang-tui-observe.adoc[Observing Integrations] | Activity, message history, errors, spans, process, HTTP
+probe, CVE audit, Kafka, SQL, memory leaks, JFR, catalog
+| xref:camel-jbang-tui-ai.adoc[AI Panel] | AI providers and local models, slash commands, project overview, AI log, the
+Ollama tab
+| xref:camel-jbang-tui-ai-agents.adoc[AI Agents] | MCP and ACP: what an AI agent can see and do, edits you confirm
+| xref:camel-jbang-tui-settings.adoc[Actions, Settings and Themes] | The actions menu, embedded shell, themes, settings,
+browser access, recording demos
|===
-=== Sending Test Messages
-
-Select *Send Message* from the F2 menu (or press *F2* then choose it):
-
-image::jbang/camel-tui-send.png[Send Message view with body editor and response area]
-
-* *Choose the route* -- use left/right arrows to pick the target route
-* *Enter the body* -- type the message body, or use `file:path/to/file` to load from a file
-* *Add headers* -- press *+* to add headers as key=value pairs
-* *Set exchange pattern* -- toggle between InOnly (fire-and-forget) and InOut (request/reply)
-* Press *Enter* to send
-
-For InOut exchanges, the response is displayed below with status, elapsed time, response headers,
-and body. Press *P* to toggle pretty-printing for JSON/XML responses.
-
-=== Doctor
-
-The Doctor checks your development environment and reports issues:
-
-* Java version (17+ required, 21+ recommended)
-* Camel catalog availability
-* JBang installation
-* Maven repository connectivity
-* Docker/Podman availability
-* Common port conflicts (8080, 8443, 9090)
-* Disk space in temp directory
-
-== Embedded Shell (F6)
-
-Press *F6* to open an embedded Camel JBang shell at the bottom (or top) of the screen. Any `camel`
-command can be run there -- `camel run`, `camel infra run kafka`, `camel cmd send`, `camel get` and
-so on -- without leaving the dashboard, and the tabs keep updating while the command runs. Press
-*F6* again to close the panel, *Shift+F6* to cycle its height, *PgUp*/*PgDn* to scroll the output
-and *↑*/*↓* to recall earlier commands (see <<_input_history>>).
-
-The shell and the AI prompt panel (*F8*) share the same space: opening one closes the other. Both
-open at the bottom by default; see *Panel Position* in <<_settings>>.
-
-== Theme
-
-The TUI ships with 21 color themes defined as CSS stylesheets:
-
-* *Dark themes* -- Dark (default), Dracula, Nord, Solarized Dark, Gruvbox Dark,
- Catppuccin Mocha, Catppuccin Frappé, Tokyo Night, Rosé Pine, Rosé Pine Moon, Kanagawa,
- Everforest, Monochrome, CRT, Turbo Pascal
-* *Light themes* -- Light, Nord Light, Solarized Light, Gruvbox Light, Catppuccin Latte,
- Everforest Light
-
-Open the *F2* actions menu and choose *Settings...* to switch themes, or pass
-`--theme=<name>` on the command line (e.g., `--theme=tokyo-night`). The CLI value
-overrides the persisted preference from `.camel-cli.properties`; runtime toggles and
-the config file still apply on later launches when `--theme` is omitted.
-
-The brand orange accent is consistent across most themes; status colors (success,
-warning, error) and borders adapt for readability on each palette. A few themes trade
-the brand accent for their own identity: Monochrome, CRT and Turbo Pascal. The Turbo
-Pascal theme recreates Borland's IDE (yellow text on the blue editor field, cyan window
-frames, grey menu bar) and also restyles source code the way that editor did: reserved
-words in white, code in yellow, comments in grey. Other themes highlight code with a
-fixed Monokai (dark) or GitHub-inspired (light) palette.
-
-Your choice is remembered: it is saved as `camel.tui.theme` in `.camel-cli.properties`
-and restored the next time you open the TUI.
-
-== Settings
-
-Open the *F2* actions menu and choose *Settings...* to change TUI preferences in one place:
-
-* *Theme* -- cycle through 21 available themes (applied immediately on save).
-* *Starting Tab* -- the tab shown when the TUI launches; any tab (primary or under *More*) can be
- chosen. Defaults to *Overview*.
-* *Select Tab* -- the tab to switch to when selecting an integration from the Overview tab.
- Defaults to *Log*.
-* *Confirm* -- whether destructive actions (quit, stop, restart, stop/start routes) show a
- confirmation dialog before executing. Defaults to *on*. Kill (*X*) always confirms regardless
- of this setting.
-* *Default Folder* -- the folder pre-filled in *Run from Folder*. The most recently used folder
- still takes precedence; this default is used only when there is no remembered folder.
-* *Panel Position* -- where the shell (*F6*) and AI (*F8*) panels open: *bottom* (default) or
- *top*.
-* *Panel Space* -- whether those panels push the tab content aside (*move*, default) or are drawn
- on top of it (*overlay*), so the tab keeps its full height underneath.
-* *AI Overview* -- the <<_ai_project_overview,AI project overview>>: *manual* (default, only with
- `/overview`), *auto* (also when the AI panel opens and the project summary is missing or out of
- date), or *off* (no `/overview`, and no AI-assisted descriptions in the tabs).
-
-Use *↑*/*↓* to move between rows, *Space* (or *←*/*→*) to cycle the theme and tab settings, type to
-edit the default folder, *Enter* to save, and *Esc* to cancel.
-
-Settings are stored under `camel.tui.*` keys (`camel.tui.theme`, `camel.tui.startTab`,
-`camel.tui.selectTab`, `camel.tui.confirmActions`, `camel.tui.defaultFolder`,
-`camel.tui.panelPosition`, `camel.tui.panelSpace`,
-`camel.tui.shell.history`, `camel.tui.ai.provider`, `camel.tui.ai.model`, `camel.tui.ai.url`,
-`camel.tui.ai.tools`, `camel.tui.ai.overview`, `camel.tui.ai.promptHistory`) in the Camel CLI configuration file. Each key is read from and
-written back to the file where it currently lives: a key present in the local
-`./camel-cli.properties` is treated as a project-level override and stays local, while every
-other key defaults to the global `~/.camel-cli.properties`. This means a project can
-deliberately pin a starting tab in its local config without redirecting your personal theme
-into the project file. See xref:camel-jbang-configuration.adoc[Configuration] for details
-on the global and local files.
-
-=== Input history
-
-The embedded shell (*F6*) and AI prompt (*F8*) keep a recall list for the command line and prompt
-respectively. Use *↑*/*↓* on the input line to walk previous entries. Limits are configured with
-`camel.tui.shell.history` and `camel.tui.ai.promptHistory` in `.camel-cli.properties` (default
-`100` each; set to `0` to disable recall and persistence). Shell history is stored in
-`~/.camel/tui-shell.history`; AI prompt history in `~/.camel/tui-ai-prompt.history`.
-
-=== Pasting
-
-Both panels accept text pasted from the terminal (for example a model name such as
-`qwen3.6:35b-a3b` after `/model`). In the AI prompt, line breaks in the pasted text are collapsed
-to spaces so the paste stays a single prompt you can review before pressing *Enter*. In the shell,
-line breaks are sent as *Enter*, so a multi-line paste runs line by line as in a regular terminal.
-
== Keyboard Shortcuts
=== Global (All Tabs)
@@ -718,775 +239,6 @@ line breaks are sent as *Enter*, so a multi-line paste runs line by line as in a
See the xref:camel-jbang-tui-source-editor.adoc#_keyboard_shortcuts[keyboard shortcuts] of the Source Editor.
-=== Diagram Tab
-
-[cols="2,5",options="header"]
-|===
-| Key | Action
-
-| *Arrow keys* | Navigate between route boxes (topology) or EIP nodes (drill-down)
-| *Enter* | Drill down into selected route / jump to linked route
-| *Esc* | Go back (previous route or topology)
-| *t* | Jump to topology view
-| *m* | Toggle metrics overlay
-| *e* | External systems: in the topology off, edges, all; in the architecture off or edges
-| *a* | AI-assisted parts shown, or the facts alone; without a `camel-summary.md` yet, has the AI write one
-| *b* (or *n*) | Business view (labels, what capabilities achieve) or technical view (route ids, endpoints)
-| *c* | View route source code
-| *v* | Next level: Architecture, Topology, Route
-| *u* | In the architecture and the topology: show or hide the utility routes
-| *g* | In the topology: show each route's group (route group, AI capability, shared services, utility)
-| *s* | Open the integration summary (`camel-summary.md`) in the document viewer, from any level
-|===
-
-=== Inspect Tab
-
-[cols="2,5",options="header"]
-|===
-| Key | Action
-
-| *Up/Down* | Navigate between steps
-| *b* / *h* / *p* / *v* | Toggle body / headers / properties / variables
-| *w* | Toggle word wrap
-| *g* | Toggle waterfall view
-| *d* | Toggle diagram replay mode
-| *n* | Toggle description labels
-| *F5* | Refresh / clear traces
-|===
-
-== Highlighted Features
-
-Beyond the core tabs described above, the TUI includes several specialized screens worth highlighting.
-
-=== CVE Audit
-
-The CVE Audit tab (under More > Project) scans all Maven dependencies on your integration's classpath
-against the https://osv.dev[OSV.dev] vulnerability database. It queries every JAR using the OSV batch
-API and displays known vulnerabilities grouped by severity (Critical, High, Medium, Low).
-
-Each vulnerability shows the CVE ID, affected artifact, the direct dependency that pulls it in (VIA column),
-and a summary. Select a CVE to see full details including CVSS vector, published date, fixed versions,
-and aliases. Results are cached globally -- switching integrations that share JARs is instant.
-
-=== Kafka
-
-The Kafka tab (under More > Data) provides a dedicated view for Kafka consumers and their connectivity
-status. It shows consumer group details, topic assignments, partition offsets, and reconnection state.
-When a broker connection drops, the Recovery Tasks tab shows the reconnection task with its
-Waiting/Attempting status, retry count, and error details.
-
-=== SQL Query and SQL Trace
-
-When your integration includes a DataSource, two SQL tabs appear under More > Data:
-
-* *SQL Query* -- an interactive SQL console where you can write and execute queries against any
- DataSource in your integration. Results are displayed as a formatted table with column types.
-* *SQL Trace* -- captures and displays SQL statements executed by your routes in real-time,
- showing query text, execution time, and the route that triggered them.
-
-=== Memory Leak Detection
-
-The Memory Leak tab (under More > JVM) uses Java Flight Recorder (JFR) to diagnose memory leaks
-in your running integration. It runs two sequential recordings and compares object retention trends,
-classifying each class as growing, stable, shrinking, new, or gone. This is lightweight and safe
-for production use.
-
-=== JFR Runtime Profiling
-
-The JFR tab (under More > Observability) gives you a lightweight profiling view of your running integration
-using Java Flight Recorder. JFR is built into the JVM with very low overhead, making it suitable
-for near-production use cases where you need timing data without impacting throughput.
-
-Start your integration with JFR runtime instrumentation enabled:
-
-[source,bash]
-----
-camel run my-route.yaml --jfr
-----
-
-The JFR tab shows the recording status and event configuration. Press *F5* to take a snapshot
-of the active recording -- the TUI aggregates all Camel events and presents them in five views:
-
-* *Routes* (key *1*) -- per-route totals, failure counts, and min/mean/max duration
-* *Processors* (key *2*) -- per-processor statistics with type and owning route, sorted by slowest first
-* *Endpoints* (key *3*) -- per-endpoint send statistics with duration
-* *Failures* (key *4*) -- recent exchange failures with exception type and message
-* *Redeliveries* (key *5*) -- recent redelivery attempts with attempt and max counts
-
-Press *Enter* on a route to drill down into its processors filtered by that route.
-Press *s* to cycle sort columns, and *Esc* to go back.
-
-Each snapshot is a point-in-time read -- the recording keeps running, so you can press *F5*
-again at any time to see updated statistics as more messages flow through the system.
-
-=== Catalog
-
-The Catalog tab (under More > Project) lets you browse the full Camel component catalog from within
-the TUI. Search for components by name, view their documentation, options, and supported headers --
-useful when building routes and you need to check what options a component supports.
-
-== AI Integration (MCP)
-
-The TUI includes an embedded https://modelcontextprotocol.io/[MCP] (Model Context Protocol)
-server that lets AI coding assistants interact with the dashboard.
-
-The TUI is fully functional on its own -- AI integration is entirely optional.
-
-=== Choosing an AI provider
-
-Press *F8* to open the built-in AI prompt panel. The panel auto-detects a provider in this order:
-
-1. `ANTHROPIC_API_KEY` → Anthropic Claude
-2. `CLOUD_ML_REGION` + `ANTHROPIC_VERTEX_PROJECT_ID` → Vertex AI
-3. `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` → Azure OpenAI
-4. `GEMINI_API_KEY` → Google Gemini
-5. `OPENAI_API_KEY` → OpenAI
-6. `LLM_API_KEY` + optional `LLM_BASE_URL` → any OpenAI-compatible server
-7. Ollama at `localhost:11434` → local Ollama (auto-detected, no key needed)
-
-Press *Ctrl+P* inside the AI panel to switch provider or model at any time.
-
-A question can span several lines: *Ctrl+N* starts a new line (terminals deliver *Shift+Enter* and
-*Alt+Enter* as a plain *Enter*, so they cannot be used), pasted text keeps its line breaks, and *Up* and
-*Down* move between the lines of the question before they recall earlier prompts. *Enter* sends it.
-
-The same guidance, together with the provider that is currently detected, is available inside the TUI
-via *F2* -> _AI & MCP_ -> _Setup AI_. Use *F2* -> _Settings_ to pin a provider, model or base URL
-(`camel.tui.ai.provider`, `camel.tui.ai.model`, `camel.tui.ai.url`) regardless of the environment.
-`camel.tui.ai.acp.command` sets the command line of the custom ACP agent (`acp:custom`).
-
-==== Using Ollama (local, no API key)
-
-Install Ollama natively for best performance — the native binary uses GPU acceleration
-(Metal on macOS, CUDA/ROCm on Linux):
-
-[source,bash]
-----
-# macOS
-brew install ollama
-
-# Linux
-curl -fsSL https://ollama.com/install.sh | sh
-
-# Pull a model — then open the TUI and press F8
-ollama pull qwen3.6:35b-a3b
-camel tui
-----
-
-Ollama at `localhost:11434` is auto-detected. No configuration needed.
-
-IMPORTANT: The F8 AI panel works by invoking built-in tools to inspect your running Camel process.
-Models smaller than ~14B do not reliably call tools and answer from training knowledge instead.
-Use at least a 14B model. Prefer a mixture-of-experts model such as `qwen3.6:35b-a3b`: with only
-3B parameters active per token it processes the tool-heavy prompt many times faster than a dense
-27B/32B model, so answers start in seconds instead of a minute.
-
-*Models that work well* (tool-calling capable, ≥14B, default Q4_K_M quantization):
-
-[options="header"]
-|===
-| Model | RAM | Notes
-| `qwen3.6:35b-a3b` | ~23 GB | Recommended: fastest prompt processing, needs 32 GB+
-| `qwen2.5:14b` | ~9 GB | Minimum for 16 GB machines
-| `qwen3.6:27b` | ~18 GB | Strong dense model, several times slower prompt processing
-| `qwen2.5:32b` | ~20 GB | Good quality, slow prompt processing
-| `hermes3:70b` | ~43 GB | Excellent tool calling, needs 64 GB+
-| `llama3.3:70b` | ~43 GB | Best open model, needs 64 GB+
-|===
-
-NOTE: `camel infra run ollama` runs Ollama in Docker and bypasses GPU acceleration,
-making inference significantly slower. Native install is preferred for development.
-
-NOTE: On Apple Silicon, use the default (GGUF) tags rather than the `-mlx` tags. The Ollama MLX
-engine cannot yet reuse the cached prompt for Qwen 3.x models, so every question re-processes the
-whole prompt, while the default engine reuses it and only processes what is new.
-
-==== Tool set for local models
-
-Every question sends the definitions of the `tui_*` tools the model may call, and a local model
-pays for each of them in prompt-processing time. The panel therefore sends only the core set of
-tools (state, tables, logs, errors, diagrams, topology, processor details, catalog docs, traces,
-spans, route control, sending messages, source files, infra services, navigation, log level and
-filters) to Ollama
-and to any provider on `localhost`, which roughly halves the prompt. Hosted providers get every
-tool, including the drawing, animation and automation tools. Use `/tools full` in the panel to send
-all tools to a local model too, `/tools core` to trim the set for a hosted one, pick *AI Tools* in
-*F2 -> Settings*, or set `camel.tui.ai.tools` in `.camel-cli.properties`. Ollama requests also ask the server to keep the
-model loaded for 30 minutes and for a context window of 32k or 64k (see <<_working_with_a_local_ollama_model>>;
-`OLLAMA_CONTEXT_LENGTH` overrides it), so follow-up questions reuse the cached prompt instead of reloading
-the model.
-
-==== Working with a local Ollama model
-
-A local model is not a slower version of a hosted one; it spends its time differently, and the TUI
-shows you where. This section explains what a question costs with Ollama and which knobs matter,
-with figures measured on an Apple M4 Pro (64 GB) running `qwen3.6:35b-a3b`.
-
-*How a question is spent.* Ollama answers in three phases, and every timing the TUI shows maps to one
-of them:
-
-1. *Load*: if the model is not in memory (first question, the keep-alive expired, or a request asked for
- a different context size) Ollama starts a runner and loads the weights: 10 to 20 seconds for a 22 GB
- model. The TUI asks Ollama to keep the model loaded for 30 minutes after each request.
-2. *Prefill*: the prompt (system prompt, tool definitions, conversation history, your question) is
- processed in one batch, at roughly 600 to 700 tokens per second when nothing is cached.
-3. *Decode*: the answer is generated token by token, at 50 to 60 tokens per second for this model.
-
-The wait before anything appears, the time to first token, is load plus prefill. A cold first question
-therefore takes 20 seconds before the first word; a warm one under a second.
-
-*One question, many requests.* The panel answers by calling the `tui_*` tools, and every tool call the
-model makes costs a new request that sends the whole prompt again. A simple question can take 3 to 13
-requests. This is affordable only because Ollama caches the prompt prefix: the system prompt, the tool
-definitions and the history are identical from one step to the next, so each step prefills only the new
-tokens and takes about half a second. Across a session the cache hit is typically above 90%. The
-Ollama tab shows the request count per question as `×N` and the cache hit per question; a question
-with a high count and a short answer is the model exploring, which a smaller, sharper tool set reduces
-(see <<_tool_set_for_local_models>>).
-
-*The context window.* The TUI decides the window it asks Ollama for (`num_ctx`) once per model:
-
-1. `OLLAMA_CONTEXT_LENGTH` in the environment wins when set.
-2. If the model is already loaded, its window is adopted (raised to 32k when smaller), so the TUI never
- makes Ollama reload a model another client is using. A request with a different `num_ctx` costs a
- cold start and throws away everyone's prompt cache.
-3. Otherwise 64k when the model's weights plus the KV cache of a 64k window fit the machine's memory,
- computed from what `ollama show` reports (layers, KV heads, head size), else 32k. Overshooting is
- worse than being conservative: Ollama then moves layers to the CPU and generation slows to a crawl.
-
-The static prefix of system prompt and core tools is about 4.5k tokens, and each question with tool
-calls adds another 2k to 4k of history. The panel compacts the history once the prompt Ollama measured
-for the last request passes half the window, capped at half of 64k even when a larger window was
-adopted: every token of history is prefill time again after a cache loss (an idle unload after 30
-minutes, another client, a restart), and 64k at a few hundred tokens per second is already well over a
-minute. Compacting rewrites the history, which invalidates Ollama's prompt cache, so the request after
-a compaction prefills the whole prompt again: about 40 seconds for a 21k-token prompt. The panel
-therefore compacts local history rarely and then thoroughly, down to about a quarter of the window,
-and prints one line saying what it did and how long the next reply will take to start. `/compact` does
-the same on demand with the same line; `/context` shows the window, the compaction point and the last
-measured prompt; the panel title shows the fill as `ctx 34%`.
-
-*Choosing the model.* With no `camel.tui.ai.model` set the panel takes `llama3.2` when it is installed,
-otherwise the first installed model; run `/model <name>` in the panel or set *AI Model* in
-*F2 -> Settings* to pin one. The model must support tool calling and should have at least 14B
-parameters; a mixture-of-experts model such as `qwen3.6:35b-a3b` prefills several times faster than a
-dense model of similar quality, which is what matters for a tool-heavy prompt. *F2 -> Run Doctor* shows
-whether Ollama was found, which models are installed and whether they are large enough.
-
-*Where to look.* The <<_ollama>> tab is the instrument for all of the above: tokens per second live and
-per request, time to first token with cold starts marked, cache hit, how full the context window is
-and how it grows per question, GPU and process load, and one line per question with the requests it
-took, the question being answered right now on top with `working` as its reason and its time counting
-up, and a footer with the average per question. In the AI panel, `/context` prints what the next request will cost, `/usage` and *Ctrl+U* the
-session totals per question.
-
-*Remote and containerised Ollama.* Everything above applies to an Ollama on another host or inside
-`camel infra run ollama` as well, with two differences: the container runs without GPU acceleration,
-and the live runner state and host load on the Ollama tab need the server on the same machine.
-
-For the wider picture see the blog posts
-link:/blog/2026/09/camel-local-model-benchmark/[We had a frontier AI coach a small local model through Camel]
-on what a local model can do with Camel and what was changed to help it, and
-link:/blog/2026/09/camel-genai-observability-jbang/[Observe Your Camel AI Routes with GenAI OpenTelemetry]
-on observing routes that call Ollama.
-
-==== Using an OpenAI-compatible local server
-
-Set `LLM_API_KEY` and `LLM_BASE_URL` to connect to any OpenAI-compatible server
-(LM Studio, vLLM, llama.cpp, GPT4All, …):
-
-[source,bash]
-----
-export LLM_API_KEY=any-value
-export LLM_BASE_URL=http://localhost:1234
-camel tui
-----
-
-`OPENAI_BASE_URL` is also accepted as an alternative to `LLM_BASE_URL`.
-
-The panel uses the first model the server lists on `/v1/models`. To use another one, run
-`/model <name>` in the panel (`/model` alone lists what the server offers), set *AI Model* in
-*F2 -> Settings*, or set `camel.tui.ai.model`. The model must support tool calling, otherwise the
-panel answers from training data instead of inspecting your integration. When a request fails, the
-panel shows the HTTP status and the server's error message, for example a model that the server
-does not host.
-
-=== Why This Matters
-
-When an AI agent connects to the TUI via MCP, it gains the same level of visibility that you
-have -- and can act on it. The agent can:
-
-* *Read everything* -- route topology, statistics, message traces, errors, logs, source files,
- health checks, and JVM metrics
-* *Navigate and control* -- switch tabs, select routes, start/stop routes, send test messages,
- change log levels
-* *Teach and present* -- the AI can control the TUI screen to walk you through concepts,
- highlight areas of interest, draw annotations, and take screenshots. It can circle a failing
- route, draw arrows between connected endpoints, and add explanatory text labels -- turning the
- TUI into a live whiteboard for pair-programming
-* *Self-troubleshoot* -- when something fails, the AI can autonomously inspect the error,
- read the message trace, correlate with route statistics, and produce a diagnostic report
- with annotated screenshots showing exactly where and why the failure occurred
-
-=== Enabling MCP
-
-[source,bash]
-----
-camel tui --mcp
-----
-
-This starts an MCP server on `localhost:8123` (configurable with `--mcp-port`).
-The server is bound to `127.0.0.1` only -- it never listens on external interfaces.
-
-When MCP is active, the TUI footer shows the connection status.
-Use *F2* -> _MCP Info_ to see server details and _MCP Log_ to view the tool call history.
-
-=== Status document resources
-
-Every running integration keeps a full status document in `~/.camel/<pid>-status.json`, written
-once a second by `camel-cli-connector`. The tabs show a digest of it; the MCP server exposes the
-whole document as resources so an agent can fetch exactly the section it needs instead of
-paging through tabs:
-
-* `camel://log/<pid>` -- the last 200 lines of the integration's log (`~/.camel/<pid>.log`);
- `camel://log/<pid>?lines=<n>` for a different tail length (up to 5000). The Log tab shows only a
- window of this file, so an agent that needs to know which lines the user is looking at should
- use the `tui_get_screen` tool instead.
-* `camel://status/<pid>` -- the whole document
-* `camel://status/<pid>/<section>` -- one top-level section, for example `context` (name, version,
- state, uptime, start timestamp, statistics), `runtime`, `routes`, `endpoints`, `healthChecks`,
- `properties`, `main-configuration`, `routeController`, `memory`, `threads`, `gc` or `events`
-
-`resources/list` enumerates the log, the document and its sections for every monitored
-integration, and `resources/templates/list` describes the URI shapes. The same data is available to the
-F8 AI panel (and as an MCP tool) through `tui_get_status`, which takes a `section` argument and
-returns that section only; pass `sections` to list what the document contains. Sections such as
-`events` can be large, so ask for the one you need.
-
-=== AI panel slash commands
-
-When the AI panel is open, input that starts with `/` runs a local panel command instead of sending a question to the configured AI provider. `/provider` and `/model` are unavailable while a response or command is already in progress; the panel shows a message asking you to wait.
-
-Press *Tab* to complete a command name. After `++/model ++` *Tab* completes the model name against the
-models the current provider reports (the list is fetched in the background on the first press, so
-press *Tab* again once it has arrived), and after `/tools ` it completes `auto`, `core` or `full`.
-With several matches *Tab* fills in the common prefix and then cycles through them; *Shift+Tab*
-cycles backward.
-
-[cols="1,3",options="header"]
-|===
-| Command | Description
-
-| `/help` (`/h`)
-| Show the available slash commands.
-
-| `/provider` (`/p`)
-| Open the provider switcher.
-
-| `/model [model-name]` (`/m`)
-| Show the current model, or switch the session model.
-
-| `/write [confirm\|auto\|live]` (`/w`)
-| Show or switch how file writes by the model (`camel_write_file`) are handled. `confirm` (default) shows the confirm dialog for every write, whatever the model passes; `auto` lets the model skip the dialog with `confirm=false`; `live` replays the edit in the Source editor so you watch it happen (see below). The mode lasts for the session.
-
-| `/tools [auto\|core\|full]` (`/t`)
-| Show which tool set is sent to the model, or switch it. `auto` (default) sends the core set to local providers and every tool to hosted ones; the choice is saved as `camel.tui.ai.tools`.
-
-| `/context` (`/ctx`)
-| Show what the next request costs: provider and model, tool set, static prefix size, history size and the session total, and with Ollama the context window, the prompt size above which the history is compacted and the last measured prompt. Useful with local models, where prompt size is time.
-
-| `/compact`
-| Shrink the conversation history sent to the model right away: older tool results are cut to their first lines and the oldest turns are dropped. With a hosted provider the panel does this automatically after each answer for all but the latest turn. With Ollama or another `localhost` provider it waits until the prompt Ollama measured passes half the context window (see <<_working_with_a_local_ollama_model>>), then compacts thoroughly, because a local server can reuse its cached prompt on [...]
-
-| `/retry`
-| Send the last question again, starting from a clean turn in the model history.
-
-| `/usage [reset]` (`/u`)
-| Print the AI usage so far in the chat: requests, tokens in and out, average latency, one line per model (and per route when GenAI spans are observed), and the last request. *Ctrl+U* opens the full view with the per-question chart. `/usage reset` clears the counters and the chart without touching the conversation; GenAI spans recorded before the reset are hidden from the view as well.
-
-| `/copy` (`/y`), `/export` (`/e`)
-| The same as *Ctrl+Y* (copy the last response) and *Ctrl+E* (export the conversation to Markdown). Copying is code-aware: when the response has one fenced code block only the code is copied (without the fences and the prose, which is what selecting it with the mouse cannot give you because of the panel borders); when it has several, a picker lists the blocks with their language and size plus the whole response; when it has none, the whole response is copied.
-
-| `/prompt`
-| Show the system prompt the panel sends with every request.
-
-| `/clear` (`/c`)
-| Clear the AI conversation, usage counters, and model context without changing the provider or model.
-
-| `/close`
-| Close the AI panel.
-
-| `/quit` (`/exit`, `/q`, `/x`)
-| Exit the TUI.
-
-| `/run <camel run args>` (`/r`)
-| Run `camel run` with the provided arguments.
-
-| `/infra <camel infra args>` (`/i`)
-| Run `camel infra` with the provided arguments.
-
-| `/overview [refresh\|show\|apply]` (`/o`)
-| The <<_ai_project_overview,AI project overview>> of the selected integration's project: without an argument it shows the summary when it is up to date and asks the model to explain the project otherwise; `refresh` explains it again, `show` opens the summary file in the document viewer, `apply` puts the suggested route descriptions into the route sources.
-
-| `/send <endpoint> <message text \| @file>` (`/s`)
-| Send a message through `camel cmd send`. A body that is exactly one `@file` token is sent as `file:<path>`; inline `@file` text is sent literally.
-|===
-
-=== AI project overview
-
-A route diagram of many routes becomes spaghetti quickly, above all when the routes have no
-`description`. `/overview` asks the model to explain the project of the selected integration (or the
-folder the TUI runs in): an overview of what it does, the business capabilities its routes implement,
-and a description of each route that has none. The facts come from the route sources, the same ones
-`camel overview` prints (see xref:camel-jbang-ai.adoc#_project_overview[Project overview]): routes,
-entry points, how routes connect, external systems and findings. The model gets them with excerpts of
-the routes (values of passwords, tokens and other sensitive options masked) in one request without
-tools, so a local model does it as well as a hosted one. It runs in the background and the answer
-appears in the panel.
-
-The answer is saved in `camel-summary.md` in the project directory, a Markdown file you can read,
-review and commit. The TUI treats it as the project's generated README: `/overview show`, or *s* in the
-Diagram tab, opens it rendered in the document viewer (*t* lists its sections), at the routes from the
-topology and at the Architecture section from the architecture view. The title says when the routes changed since
-the AI wrote its part. A project without a summary gets the facts derived from its sources, with a note
-on how to add the AI part. In the Overview tab a project with a summary shows the 📖 mark, as one with a
-README does. Its AI-assisted sections are marked `✦ AI-assisted` and kept apart from the
-sections derived from the sources, and the file records the model, the date and a fingerprint of the
-routes, so the TUI knows when the routes changed afterwards: `/overview` then explains them again.
-
-A route description comes in two parts: a short label, and a note of a sentence or two, the
-`description` and `note` of a route in the DSL. The model writes both for a route that lacks them.
-
-What an AI wrote is never shown as if it came from the source or the runtime. When a route has no
-description of its own, the *Routes* tab (with descriptions on, *n*) and the topology in the *Diagram*
-tab show the suggested label in italic, in the `ai-assisted` theme color, marked with `✦`. The *Info*
-panel beside the topology shows the whole label and note of the selected route, word-wrapped, the
-AI-assisted parts marked the same way. Once you agree with them, `/overview apply` puts the suggestions
-into the route sources (`description` and `note` in YAML and XML, `.routeDescription(...)` and
-`.routeNote(...)` in Java); each changed file goes through the confirm dialog with its diff, whatever the
-`/write` mode. From then on they are part of the routes and no longer marked.
-
-With *AI Overview* set to *auto* in *F2 -> Settings*, the panel explains the project by itself when
-it opens and the summary is missing or out of date, once per project state. External AI agents get the
-same through the `camel_project_overview` and `camel_save_project_summary` tools; from the TUI's MCP
-server the summary they save goes through the confirm dialog too.
-
-Submitted prompts (including slash commands) participate in AI prompt history when
-`camel.tui.ai.promptHistory` is not `0`. Use *↑*/*↓* on the prompt line to recall them.
-
-Every answer ends with a byline saying what the question cost: the time it took, how many tools the
-model called and the time spent in them, the number of requests, the tokens and, with Ollama, how full
-the context window got (for example `61.1s · 25 tool calls, limit reached (2.5s in tools) · 26 requests
-· 231.3k tokens · ctx 18%`). The panel allows 25 tool calls per question. When the model reaches that
-the byline says `limit reached`, the panel asks the model to answer from what it has found so far, and
-the <<_ollama>> tab shows the question's request count in red with `limit` as its reason (the count is
-yellow from 10 requests, and the total time yellow from 30 seconds and orange from a minute). A question
-that runs into the limit is usually a tool that makes the model guess, not a weak model: the AI log
-shows which one.
-
-What the model says is checked like what it writes. A file goes through the validator before
-`camel_write_file` writes it; the answer shown in the chat is what you copy, so its simple expressions
-are checked against the catalog too: the `${...}` placeholders in the text and in Java or XML code
-blocks, and the `simple:` values and log messages of YAML blocks. A small model tends to put the
-operator inside the placeholder (`${header.user ?: 'Guest'}` instead of `${header.user} ?: 'Guest'`).
-When the check finds such an expression the panel sends the answer back to the model once, with what is
-wrong and the rule, and shows the corrected answer with `1 correction` in the byline. When the model
-does not fix it the answer is shown as it is with a *Simple check* line under it naming the expression
-and the error, and the AI log has the exchange. Placeholders that are not simple (a Maven
-`$\{camel-version}`, a shell variable) are left alone.
-
-Press *Ctrl+U* while the AI panel is open to toggle the AI Usage view. It shows token consumption from
-the embedded AI prompt (*TUI ask*) and from LLM calls made by the monitored integration (*integration*),
-the latter taken from OpenTelemetry GenAI spans when observability is enabled on the integration. The
-*Tokens per question* chart has one bar per question you asked, so a question that needed several tool
-calls shows as a single bar. The summary line splits the session time into *AI time* (waiting for the
-model) and *Tool time* (running the TUI tools the model called, with the number of calls), the summary line gives the
-average time per question (and per request in brackets), the model table has an *AVG/REQ* column with
-the average per request for that model, and the *Time per question* chart next to the token chart shows the
-two side by side for each question, so you can see whether a slow answer was the model or the tools.
-
-=== AI log
-
-Every request the panel makes is recorded in the AI log (*F2* -> _AI & MCP_ -> _AI Log_, or the
-`tui_get_ai_log` tool): the question, each tool the model called with its arguments, the result with
-how long the tool took, and a `Response` line with the elapsed time and the token counts. When the
-model called tools, the elapsed time is broken down into the time spent waiting for the model and the
-time spent in tool calls (for example `5.2s, ai 4.1s, tools 1.1s/3`). The `Response` line
-also shows whether the provider reused its cached prompt. For Ollama it prints the prompt-processing
-(`prefill`) and generation (`gen`) time reported by the server -- a prefill of a fraction of a second
-on a 10k-token prompt means the cache was hit, while a prefill of several seconds means the whole
-prompt was processed again. For OpenAI, Anthropic and Gemini it prints the number of `cached` input
-tokens the provider reported. Use it to check that follow-up questions are cheap before blaming the
-model for being slow.
-
-=== Using a coding agent (ACP)
-
-Instead of talking to a model directly, the AI panel can hand the conversation to an external coding agent that
-speaks the https://agentclientprotocol.com[Agent Client Protocol] (ACP). The TUI starts the agent as a subprocess,
-gives it the TUI's own MCP server, and shows the agent's answer, tool calls and questions in the panel. The agent
-drives the TUI through the same `tui_*` tools that external MCP clients use, and can also read and edit your
-route sources with its own tools.
-
-Press *Ctrl+P* in the AI panel and pick one of the agents:
-
-[options="header"]
-|===
-| Provider | Command the TUI runs | Before the first question
-| `acp:claude` | `npx -y @agentclientprotocol/claude-agent-acp` | log in with the `claude` CLI, or set `ANTHROPIC_API_KEY`
-| `acp:codex` | `npx -y @agentclientprotocol/codex-acp` | `codex login`, or set `OPENAI_API_KEY`
-| `acp:bob` | `bob acp` | set `BOBSHELL_API_KEY`, or run `bob` once to sign in
-| `acp:qwen` | `qwen --acp` | set `OPENAI_API_KEY` and `OPENAI_BASE_URL`
-| `acp:opencode` | `opencode acp` | `opencode auth login`
-| `acp:dsh` | `npx -y @deepseek-ai/dsh --profile acp` | configure the model key in DeepSeek Harness (developer preview)
-| `acp:custom` | the value of `camel.tui.ai.acp.command` | depends on the agent
-|===
-
-The `npx` entries need Node.js 22 or newer (the Claude adapter requires it). The agent starts with your first
-question; the first start can take a while when `npx` has to download the adapter. Once the session is open the
-panel shows a two-row header with the agent's coloured glyph, the agent's name and version, the session id, the
-working directory and the number of commands it advertises. Use *F2* -> _Settings_ to make an
-agent the default provider or to set the custom command (a plain command line split on whitespace, no quoting).
-
-The MCP server is started automatically on a random localhost port when an agent needs it, so `--mcp` is not
-required. *F2* -> _MCP Info_ shows the port and the tool calls the agent makes. Like the server started with
-`--mcp`, it is bound to `127.0.0.1` with no authentication, and it rejects requests that carry an `Origin`
-header (so a web page cannot reach it) or that are not JSON.
-
-Permissions: calls to the TUI's read-only tools (the `tui_get_*` tools, catalog documentation, expression
-evaluation, locate, validate) are approved without asking. So is `camel_write_file` while the write mode is
-`confirm` or `live`, because the TUI itself asks before the file is touched (the diff dialog or the live replay
-in the Source editor); with `/write auto` the permission popup is the only question and stays. A tool that
-changes anything else, such as `camel_control`, `tui_send_message` or `tui_execute_sql`, opens the same popup as
-any other request; answering "Always allow" makes it a one-time question per tool. For anything else the agent
-wants to do, such as editing a file with its own tools or running a command, a popup shows the agent's options;
-*Enter* selects, *Esc* rejects that one call and lets the turn continue, and *Ctrl+C* cancels the whole turn.
-The preamble tells the agent to edit route sources through `camel_write_file` rather than its own file tools, so
-that you see the diff or watch the edit; when it still asks to edit a file directly, the popup says so and *Esc*
-sends it back to `camel_write_file`.
-"Always allow" choices are remembered by the agent for the session. The model, reasoning settings and any
-"always allow" rules are configured in the agent, not in the TUI; `/model` only reports the agent in use.
-
-The agent's own slash commands, for example Claude Code skills, appear as `/agent:<name>` in the `/` completion
-hints once the session is open; `/agent:` alone lists them. `/agent:<name> …` always reaches the agent, even when
-the name is also a panel command (`/agent:clear` clears the agent's context, `/clear` the panel). Anything else
-starting with `/` that is not a panel command is sent to the agent as is.
-
-The panel's own `/retry` resends the last question (or `/agent:` command) to the agent. `/context` shows the agent,
-its session, working directory, MCP server and the size of the preamble instead of a model history, and `/prompt`
-shows that preamble, sent once per session ahead of the first prompt. `/compact` and `/tools` do not apply while an
-agent is selected: the agent manages its own history and reaches the camel-tui tools through the MCP server; the panel
-says so and points to `/agent:compact` when the agent offers that command.
-
-If the agent asks for authentication and can sign you in itself, the TUI triggers that flow once; otherwise the
-panel shows the login command from the table above.
-
-NOTE: Gemini CLI, Google Antigravity and Pi are not offered as presets. Gemini CLI stopped serving personal Google
-accounts in June 2026, Antigravity's CLI has no ACP mode yet, and Pi's community adapter does not pass MCP servers
-through. Any ACP agent can still be tried through `acp:custom`.
-
-=== Connecting an AI Agent
-
-To connect Claude Code to the TUI, add the MCP server to your project configuration
-(`.mcp.json` in your project root):
-
-[source,json]
-----
-{
- "mcpServers": {
- "camel-tui": {
- "type": "url",
- "url": "http://localhost:8123/mcp"
- }
- }
-}
-----
-
-=== What AI Agents Can Do
-
-The MCP server exposes two kinds of tools. The `camel_` tools are the Camel authoring set shared with the
-`camel mcp` server (see xref:camel-jbang-mcp.adoc[]): catalog documentation with the endpoint URI rules and the
-simple syntax (`camel_catalog_doc`, `camel_catalog_find`), source validation (`camel_validate_source`), reading
-and writing the source files (`camel_get_files`, `camel_write_file`), running an integration in dev mode and
-controlling it (`camel_run`, `camel_control`), its log and failed exchanges (`camel_get_log`, `camel_get_errors`),
-expression evaluation (`camel_eval_expression`) and error diagnosis (`camel_error_diagnose`). They are defined
-once in the Camel CLI, so an agent gets the same tools, names and answers through either server; in the TUI
-they work on the selected integration unless a `directory` or `name` argument says otherwise, and a write goes
-through the TUI's confirm dialog or live replay. The `tui_` tools are the ones only the TUI can offer, organized
-by purpose:
-
-* *Observe* -- read the screen, get structured state, query tables/logs/errors/traces/topology/diagram/files,
- list the running infra services (brokers, databases) and read their logs, read the performance of the
- local Ollama server (`tui_get_ollama`: loaded model, tokens per second, context fill, host load, request log)
-* *Navigate* -- switch tabs, select integrations, select routes, send keystrokes, apply filters
-* *Act* -- send test messages to endpoints, start/stop/restart routes, change log levels,
- list and launch the bundled examples, start/stop/restart infra services, run any entry of
- the *F2* actions menu by its label
-* *Edit* -- write a source file in the integration's source directory (`camel_write_file`), see below
-* *Annotate* -- locate text and diagram nodes by coordinates, draw shapes (boxes, highlights,
- arrows, underlines, text labels), show captions with typewriter animation
-* *Present* -- take screenshots, record tape sessions, control demo pacing
-
-=== Editing source files from an AI agent
-
-The TUI is for prototyping, human and AI together, so an agent (the built-in *F8* panel or an
-external MCP client) can change the routes it is looking at. `camel_get_files` tells the agent where
-the sources are, which differs with how the integration was started (plain files, `--source-dir`,
-an example extracted to a temporary folder, or an exported project), and whether editing makes
-sense: `devMode` (changes are reloaded automatically), `temporary` (a copy that is lost when the
-integration stops) and an `editing` hint. `camel_write_file` then writes the complete new content of
-a file in that directory.
-
-An integration started with `--runtime=spring-boot` or `--runtime=quarkus` runs from an exported Maven
-project, where the routes sit under `src/main/resources/camel` rather than next to a `pom.xml`. The
-listing understands that layout: it names the route and configuration files first, lists every file
-with its path relative to the project (build output skipped), and maps each running route to its file
-and line, so the agent reads the right file in one call instead of guessing names. File paths given to
-`camel_get_files` and `camel_write_file` are relative to that directory and may name a subdirectory.
-
-Every write is confirmed in the TUI first: a dialog names the file, the directory and the size of the
-change (`+3 -1` lines); press *d* to see the change as a unified diff, with removed lines on red and
-added lines on green like the Source tab's *F7* diff, and scroll it with the arrow keys; *Enter*, *Esc* or
-*d* returns to the summary. In the summary *Enter* applies the write and *Esc* rejects it, in which case the
-agent is told that the file is unchanged and not to retry. The dialog cannot be skipped by the agent on
-its own: `confirm=false` is honoured only after you switched to `/write auto` in the AI panel (the default
-`/write confirm` shows the dialog for every write, whatever the agent passes). Only plain file names in the source
-directory are accepted; the tool cannot write elsewhere, and there is no git integration, so the
-worst case is a wrong route file in a folder you are watching.
-
-Before writing, an agent can check its content with `camel_validate_source`, which runs the same checks as
-the Source tab's save: YAML routes against the Camel YAML DSL schema (a misspelled option such as `logLevel`
-instead of `loggingLevel` is reported) plus endpoint URIs and simple expressions, Java and XML routes read into
-the Camel model with the same endpoint and simple checks, and `.properties` files against the catalog of
-`camel.*` and Spring Boot options. `camel_write_file` runs that validation itself and
-refuses to write an invalid file, returning the errors instead, so a model fixes them rather than the user
-finding them in the log after the reload. Both tools are part of the core
-tool set, so local models (Ollama) get them as well.
-
-Simple expressions get two more helpers, because they are what a small model gets wrong most often
-(functions belong inside the `${...}` placeholder, operators between placeholders: `${header.user} ?: 'Guest'`,
-not `${header.user ?: 'Guest'}`). `camel_catalog_doc` for the `simple` language returns those syntax rules
-together with the catalog's functions and operators (their count and names by group, or with `optionsFilter`
-the matching ones with parameters and examples), and `docPage` serves the operators, functions, OGNL and
-advanced documentation pages. `camel_eval_expression` evaluates an expression inside the running integration,
-like `camel cmd eval`, or locally when no integration is selected, and returns the value or the parser error,
-so the agent can try an expression before it answers or writes it. Component lookups get the same treatment for endpoint URIs: every endpoint option
-says whether it is part of the URI path or a query parameter, and the result spells out the URI rules for
-that component (its path options, the `?option=value&option=value` form, the YAML `uri` plus `parameters`
-form, placeholders, `RAW()`, and that component options belong in `application.properties`). With
-`endpoint` the same tool checks a URI against the catalog, the way the YAML validator does on a write:
-unknown options with the closest real names, values that are not among the allowed ones, missing path
-parts, consumer options on a producer endpoint and the like, plus the options the URI uses with their
-documentation, so the agent can check an endpoint before it answers or writes it.
-
-==== Watching the AI edit (live mode)
-
-With `/write live` the change is not shown as a diff but replayed in the Source tab's editor: the AI
-panel hides so the editor has the whole screen, the file opens in edit mode, the cursor jumps to the
-first change, removed lines disappear and added lines are typed at a readable pace. The AI panel comes
-back once you have saved or discarded. This is meant for learning Camel and the YAML DSL: you see the edit land in
-the full, syntax-highlighted file and can look up what the new lines mean. Every change is its own step,
-even when changes sit a line apart, and between them the replay pauses: *Enter* continues with the next change, *Esc* stops (what was typed stays in the editor), any
-other key finishes the current change at once, and *F4* (the editor's edit key) hands the keyboard to you
-so you can edit yourself; *F9* then continues with the remaining changes. Those are located by their surrounding lines,
-so your own edits elsewhere in the file shift them rather than break them; a change whose surroundings
-you edited is skipped and reported to the agent. When the replay is over you review with *F7* and
-save with *Ctrl+S* or *F5*, which is the confirmation, or discard with *Esc*. The agent waits until then
-and is told what was applied, what was skipped, and the content of the saved file if you changed it.
-
-An edit (`camel_edit_file`, which the agent uses to change a file without rewriting it) goes the same way: the
-snippet is replaced in the file's content and the result is confirmed or replayed like any write, so what you see
-in the editor is the finished file either way.
-
-While the replay pauses you can also ask the agent about the change it just made: *F8* opens the AI panel
-with the question prefilled (`About edit 2 of 3:`), you complete it and press *Enter*. The waiting
-`camel_write_file` call returns to the agent with the question, the edits applied so far and the editor's
-content, and the agent answers in the same turn -- nothing is written meanwhile. Close the panel with *F8*
-(or *Esc* to leave without asking) and the pause continues where it was. If your question makes the agent
-revise the change, its next `camel_write_file` of the same file continues in the editor from the current
-content instead of starting over. If you save or discard without the agent being involved again, it is
-told what became of the edit with your next question.
-
-=== Example Workflows
-
-* _"What routes are failing and why?"_ -- The agent reads the errors tab, correlates with
- route statistics, steps through the failing exchange in the Inspect tab, and explains
- the root cause with annotated screenshots.
-* _"Show me how this message flows through the system"_ -- The agent navigates to the Inspect tab,
- opens the diagram replay, steps through each processor, and highlights the path on the
- topology while explaining what happens at each step.
-* _"Highlight the bottleneck routes"_ -- The agent reads the route statistics, locates the
- slowest routes on the diagram, draws red boxes around them, and adds labels with the
- processing times.
-
-See xref:camel-jbang-mcp.adoc[Camel MCP Server] for more about MCP and AI integration with Camel.
-
-== Web Browser Access
-
-The TUI can also be reached from a web browser on the same host, using the same dashboard you'd see in a
-local terminal -- useful when you prefer a browser session to a terminal window.
-
-[source,bash]
-----
-camel tui --web
-----
-
-This starts a web terminal server on `localhost:8090` (configurable with `--web-port`).
-Open `http://localhost:8090` in a browser to get a full xterm.js terminal driving the same
-TUI dashboard, with the same tabs, keyboard shortcuts, and F2 actions menu as a local session.
-
-Like the MCP server, the web server is bound to `127.0.0.1` only -- it never listens on
-external interfaces -- and there is no authentication beyond that. Each browser connection
-gets its own independent TUI session (its own process discovery and navigation state), the
-same as if you'd run `camel tui` again in a new terminal.
-
-== Recording Demos
-
-The TUI can record terminal sessions for demos and documentation.
-
-=== Live Recording
-
-Use the *F2* actions menu and select *Start Tape Recording* to start recording your session
-as a `.tape` file. Select *Stop Tape Recording* to stop. The tape captures your keystrokes
-with timing, producing a script that can be replayed or converted to an animated GIF.
-
-=== Scripted Recording
-
-Use the `--record` flag to replay a `.tape` file in headless mode and produce an
-https://asciinema.org/[Asciinema] `.cast` recording:
-
-[source,bash]
-----
-camel tui --record=demo.tape
-----
-
-The `.cast` file is written next to the tape, with the `.tape` suffix replaced by `.cast`.
-Recording is headless: the TUI is driven entirely by the tape rather than by your terminal,
-so no keyboard input is read and nothing is drawn on screen.
-
-The recorded terminal is 200x50 by default, which is wider than a documentation page can
-display. Use `--record-size` to record at a size that fits, and `--record-fps` or
-`--record-duration` to control the capture rate and the cut-off:
-
-[source,bash]
-----
-camel tui --record=demo.tape --record-size=160x44 --record-fps=15
-----
-
-`--record` cannot be combined with `--web`. Recording drives a headless TUI from the tape, and
-the recording configuration applies to the whole process, so every browser session would be
-recorded into the same `.cast` file. Camel rejects the combination with an error instead.
-
-=== Converting to GIF
-
-Convert recordings using https://github.com/asciinema/agg[agg] (for `.cast` files) or
-https://github.com/charmbracelet/vhs[VHS] (for `.tape` files):
-
-[source,bash]
-----
-agg recording.cast out.gif # .cast -> .gif
-vhs demo.tape # .tape -> .gif
-----
-
== Command Line Options
[cols="2,5,1",options="header"]