lanl · mikegros · Aug 27, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/.gitignore b/.gitignore
@@ -19,6 +19,7 @@ wheels/
 .venv/
 workspace/
 workspace_*/
+examples/**/uv.lock
 
 # ursa
 src/ursa/util/agent_memory_db/

diff --git a/README.md b/README.md
@@ -36,23 +36,14 @@ The MkDocs documentation in `docs/` is organized around installation, getting st
 You can install `ursa` as a command line app with `pip install`; or with [`uv`](https://docs.astral.sh/uv/) via
 
 ```bash
-uv tool install ursa-ai
+uv tool install 'ursa[dashboard]'
 ```
 
-A reusable YAML configuration file is the preferred way to select endpoints and runtime settings. For example:
+A standard OpenAI setup needs no configuration file:
 
-```yaml
-llm_model:
-  model: openai:gpt-5.2
-  api_key:
-    env: OPENAI_API_KEY
-workspace: .
-```
-
-Then start the command line app with:
-
-```
-ursa --config config.yaml
+```bash
+export OPENAI_API_KEY="..."
+ursa
 ```
 
 This starts the full-screen terminal app. Type `/` to browse commands,

diff --git a/configs/example.yaml b/configs/example.yaml
@@ -6,7 +6,8 @@ use_web: true
 inference_providers:
   openai_public:
     base_url: https://api.openai.com/v1
-    api_key_env: OPENAI_API_KEY
+    api_key:
+      env: OPENAI_API_KEY
 llm_model:
   # Model options depend on the selected provider:
   # https://reference.langchain.com/python/langchain/models/#langchain.chat_models.init_chat_model

diff --git a/docs/agents/acquisition/arxiv.md b/docs/agents/acquisition/arxiv.md
@@ -89,9 +89,9 @@ By default, the agent writes artifacts under the agent den:
 - final direct-summarization file: `arxiv_generated_summaries/final_summary.txt`
 - RAG workflow artifacts are managed by the shared RAG path when `rag_embedding` is provided.
 
-## CLI
+## TUI
 
-The interactive CLI registers this agent as:
+The TUI registers this agent as:
 
 ```text
 arxiv

diff --git a/docs/agents/acquisition/index.md b/docs/agents/acquisition/index.md
@@ -95,6 +95,8 @@ Acquired documents are stored under the configured `database_path` inside the ag
 
 Exact filenames and citations are determined by each concrete acquisition agent's `_id()` and `_citation()` methods.
 
-## CLI availability
+## TUI availability
 
-The interactive CLI currently registers `arxiv` and `web` acquisition agents. `OSTIAgent` is exported from `ursa.agents` for Python/API use; it is not currently registered as a CLI short name in the inspected source.
+The TUI currently registers `arxiv` and `web` acquisition agents. `OSTIAgent`
+is exported from `ursa.agents` for Python/API use; it is not currently
+registered as a TUI short name in the inspected source.
diff --git a/docs/agents/acquisition/osti.md b/docs/agents/acquisition/osti.md
@@ -97,12 +97,12 @@ By default, the agent writes artifacts under the agent den:
 - final direct-summarization file: `acq_summaries/final_summary.txt`
 - RAG workflow artifacts are managed by the shared RAG path when `rag_embedding` is provided.
 
-## CLI
+## TUI
 
 `OSTIAgent` is exported from `ursa.agents` for Python/API use:
 
 ```python
 from ursa.agents import OSTIAgent
 ```
 
-In the inspected source, it is not currently registered as an interactive CLI short name.
+In the inspected source, it is not currently registered as a TUI short name.
diff --git a/docs/agents/acquisition/web-search.md b/docs/agents/acquisition/web-search.md
@@ -96,9 +96,9 @@ By default, the agent writes artifacts under the agent den:
 - final direct-summarization file: `acq_summaries/final_summary.txt`
 - RAG workflow artifacts are managed by the shared RAG path when `rag_embedding` is provided.
 
-## CLI
+## TUI
 
-The interactive CLI registers this agent as:
+The TUI registers this agent as:
 
 ```text
 web

diff --git a/docs/agents/chat.md b/docs/agents/chat.md
@@ -21,7 +21,7 @@ state = agent.invoke("Summarize the files in this workspace.")
 print(agent.format_result(state))
 ```
 
-For conversational continuation, reuse the returned state through `format_query` or let the CLI maintain state for you.
+For conversational continuation, reuse the returned state through `format_query` or let the TUI maintain state for you.
 
 ```python
 state = agent.invoke("Remember that this project studies alloy phase stability.")
@@ -59,7 +59,7 @@ When `use_web=True`, it also binds:
 - `run_osti_search`
 - `run_arxiv_search`
 
-If persistent RAG tools are configured through `rag_tools`, `AgentWithTools` can expose those as additional tools. MCP tools can also be attached in the CLI when MCP servers are configured.
+If persistent RAG tools are configured through `rag_tools`, `AgentWithTools` can expose those as additional tools. MCP tools can also be attached in the TUI when MCP servers are configured.
 
 ## Graph behavior
 
@@ -75,11 +75,12 @@ This means `ChatAgent` can use multiple tools over multiple turns, but it does n
 
 ## BasicChatAgent
 
-The module also contains `BasicChatAgent`, a simple chat-only implementation with no tool loop. It is useful for minimal conversational behavior, but `ChatAgent` is the public, tool-capable chat agent exported by `ursa.agents` and used by the CLI `chat` behavior.
+The module also contains `BasicChatAgent`, a simple chat-only implementation with no tool loop. It is useful for minimal conversational behavior, but `ChatAgent` is the public, tool-capable chat agent exported by `ursa.agents` and used by the TUI `chat` behavior.
 
-## CLI usage
+## TUI usage
 
-In the interactive URSA CLI, use the `chat` agent. Web/search tools are opt-in:
+In the URSA TUI, use the `chat` agent. Web/search tools are opt-in through a CLI
+flag:
 
 ```bash
 ursa --use-web

diff --git a/docs/agents/dsi.md b/docs/agents/dsi.md
@@ -43,7 +43,7 @@ When initializing `DSIAgent`, you can customize its behavior with these paramete
 
 ## Advanced Usage
 
-### From the URSA CLI
+### From the URSA TUI
 ```bash
 ursa % ursa
 

diff --git a/docs/agents/index.md b/docs/agents/index.md
@@ -2,7 +2,7 @@
 
 URSA agents are reusable behaviors that can chat, plan, execute, search, maintain persistent research artifacts, reason over documents, refine prompts, or interact with external tools.
 
-The interactive command-line interface exposes common agents by short names, including:
+The TUI exposes common agents by short names, including:
 
 - `chat`
 - `plan`
@@ -30,7 +30,8 @@ Additional agents may be available depending on optional dependencies and config
 
 ## Web and external information
 
-Web/search tools are opt-in for information-control reasons. For CLI sessions, enable them with:
+Web/search tools are opt-in for information-control reasons. When launching the
+TUI, enable them with this CLI flag:
 
 ```bash
 ursa --use-web

diff --git a/docs/chatollama_setup.md b/docs/chatollama_setup.md
diff --git a/docs/cli.md b/docs/cli.md
diff --git a/docs/command_line.md b/docs/command_line.md
@@ -3,38 +3,43 @@
 You can install `ursa` as a command line app with `pip install`; or with [`uv`](https://docs.astral.sh/uv/) via
 
 ```bash
-uv tool install ursa-ai
+uv tool install 'ursa[dashboard]'
 ```
 
 To use the command line app, run
 
-```
+```bash
 ursa --llm_model.model openai:gpt-5.2
 ```
 
 This starts the full-screen terminal app. Type `/` to browse commands,
 `#` to choose an agent behavior, or `@` to insert a workspace path.
-See [Getting Started - CLI](getting-started/cli.md#full-screen-interface-controls)
-for prompt editing, multiline input, clipboard, and exit behavior.
 
 You can chat with an LLM by simply typing into the terminal.
 
-```
+```text
 How are you?
 Thanks for asking! I’m doing well. How are you today? What can I help you with?
 ```
 
 Use the required `#` macro to route a prompt to another agent behavior:
 
-```
+```text
 #plan Write a python script to do linear regression using only numpy.
 ```
 
-Agent macros route only the prompt in which they appear. Output from a previous
-agent is not automatically appended to the next prompt; quote or reference any
-needed result explicitly when switching behaviors.
+If you run subsequent agents, the last output will be appended to the prompt for the next agent.
 
-You can get a list of available command line options via
+So, to run the Planning Agent followed by the Execution Agent:
+```text
+#plan Write a python script to do linear regression using only numpy.
+
+...
+
+#execute Execute the plan.
 ```
+
+You can get a list of available command line options via
+```bash
 ursa --help
 ```
diff --git a/docs/configuration/files-and-env.md b/docs/configuration/files-and-env.md
@@ -33,23 +33,19 @@ On every platform, URSA then checks `~/.config/ursa/config.yaml` and, when
 `XDG_CONFIG_HOME` is set, `$XDG_CONFIG_HOME/ursa/config.yaml`. These user files
 are loaded in that order, with duplicates skipped. A missing file is ignored.
 
-## YAML files: preferred
+## User YAML files: preferred
+
+For defaults that should follow you across projects, edit the user config path
+listed above. A small user config is usually better than a complete copy of the
+resolved defaults. For example:
 
 ```yaml
-llm_model:
-  model: openai:gpt-5.4
-  api_key:
-    env: OPENAI_API_KEY
-workspace: ./ursa-workspace
-group: default
-use_web: false
-agent_config:
-  execute:
-    safe_codes:
-      - python
+emb_model:
+  model: openai:text-embedding-3-large
 ```
 
-Run:
+OpenAI chat needs no YAML; set `OPENAI_API_KEY` and run `ursa`. Use an explicit
+file only for a project-specific or one-off override:
 
 ```bash
 ursa --config config.yaml
@@ -89,9 +85,17 @@ URSA exposes environment-variable equivalents for many CLI settings, but for mos
 
 Example:
 
-```bash
-export OPENAI_API_KEY="..."
-```
+=== "macOS/Linux"
+
+    ```bash
+    export OPENAI_API_KEY="..."
+    ```
+
+=== "Windows PowerShell"
+
+    ```powershell
+    $env:OPENAI_API_KEY = "..."
+    ```
 
 Then in YAML:
 
@@ -104,9 +108,18 @@ llm_model:
 
 You can also set URSA configuration options directly:
 
-```bash
-URSA_LLM_MODEL__MODEL=openai:gpt-5.4 ursa
-```
+=== "macOS/Linux"
+
+    ```bash
+    URSA_LLM_MODEL__MODEL=openai:gpt-5.4 ursa
+    ```
+
+=== "Windows PowerShell"
+
+    ```powershell
+    $env:URSA_LLM_MODEL__MODEL = "openai:gpt-5.4"
+    ursa
+    ```
 
 Use `ursa --help` to view supported `URSA_...` variables.
 
@@ -148,5 +161,4 @@ ursa --config ./.ursa/config.yaml --print-config=file,resolved
 
 The complete form is `--print-config=LEVEL[+],STAGE`. Levels are `system`,
 `user`, `file`, and `final`; stages are `merged` and `resolved`. Add `+` to include
-lower-precedence sources. If you provide only a level, URSA uses the `resolved`
-stage; for example, `--print-config=user` shows resolved user configuration.
+lower-precedence sources.