lanl · mikegros · Aug 27, 2026 · Aug 11, 2026 · Aug 11, 2026 · Aug 11, 2026
diff --git a/README.md b/README.md
@@ -55,51 +55,31 @@ Then start the command line app with:
 ursa --config config.yaml
 ```
 
-This will start a REPL in your terminal.
-
-```
-  __  ________________ _
- / / / / ___/ ___/ __ `/
-/ /_/ / /  (__  ) /_/ /
-\__,_/_/  /____/\__,_/
-
-For help, type: ? or help. Exit with Ctrl+d.
-ursa>
-```
-
-Within the REPL, you can get help by typing `?` or `help`.
+This starts the full-screen terminal app. Type `/` to browse commands,
+`#` to choose an agent behavior, or `@` to insert a workspace path.
 
 You can chat with an LLM by simply typing into the terminal.
 
 ```
-ursa> How are you?
+How are you?
 Thanks for asking! I’m doing well. How are you today? What can I help you with?
 ```
 
-You can run various agents by typing the name of the agent. For example,
+Use the required `#` macro to route a prompt to another agent behavior:
 
 ```
-ursa> plan
-plan: Write a python script to do linear regression using only numpy.
-```
-
-Or by prepending the agent name to the query:
-
-```shell
-ursa> plan Write a python script to do linear regression using only numpy.
+#plan Write a python script to do linear regression using only numpy.
 ```
 
 If you run subsequent agents, the last output will be appended to the prompt for the next agent.
 
 So, to run the Planning Agent followed by the Execution Agent:
 ```
-ursa> plan
-plan: Write a python script to do linear regression using only numpy.
+#plan Write a python script to do linear regression using only numpy.
 
 ...
 
-ursa> execute
-execute: Execute the plan.
+#execute Execute the plan.
 ```
 
 You can get a list of available command line options via

diff --git a/docs/command_line.md b/docs/command_line.md
@@ -12,55 +12,29 @@ To use the command line app, run
 ursa --llm_model.model openai:gpt-5.2
 ```
 
-This will start a REPL in your terminal.
-
-```
-  __  ________________ _
- / / / / ___/ ___/ __ `/
-/ /_/ / /  (__  ) /_/ /
-\__,_/_/  /____/\__,_/
-
-For help, type: ? or help. Exit with Ctrl+d.
-ursa>
-```
-
-Within the REPL, you can get help by typing `?` or `help`.
+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.
 
 ```
-ursa> How are you?
+How are you?
 Thanks for asking! I’m doing well. How are you today? What can I help you with?
 ```
 
-You can run various agents by typing the name of the agent. For example,
-
-```
-ursa> plan
-plan: Write a python script to do linear regression using only numpy.
-```
-
-Or by prepending the agent name to the query:
+Use the required `#` macro to route a prompt to another agent behavior:
 
-```shell
-ursa> plan Write a python script to do linear regression using only numpy.
 ```
-
-If you run subsequent agents, the last output will be appended to the prompt for the next agent.
-
-So, to run the Planning Agent followed by the Execution Agent:
+#plan Write a python script to do linear regression using only numpy.
 ```
-ursa> plan
-plan: Write a python script to do linear regression using only numpy.
 
-...
-
-ursa> execute
-execute: Execute the plan.
-```
+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.
 
 You can get a list of available command line options via
 ```
 ursa --help
 ```
-
diff --git a/docs/getting-started/cli.md b/docs/getting-started/cli.md
@@ -1,119 +1,117 @@
 # Getting Started - CLI
 
-This guide walks through starting URSA from the terminal, configuring a model, chatting with the default assistant, and running the planning and execution agents.
+This guide walks through starting URSA from the terminal, chatting with the
+default assistant, and routing messages to the planning and execution agents.
 
 ## Prerequisites
 
 - URSA is installed. See [Installation](../installation/index.md).
-- You have access to an LLM endpoint.
+- `OPENAI_API_KEY` is set for the default OpenAI endpoint.
 - You have a dedicated workspace directory for files URSA may create or modify.
 
 !!! warning "Be aware of your workspace"
     The execution agent can write files and run shell commands. Be careful using workspaces with source tree or data directory you cannot risk modifying. Good practice is to make backups or copies of directories before working.
 
-## 1. Create a configuration file
+For Ollama, Anthropic, Google GenAI, custom OpenAI-compatible endpoints, and
+configuration files, see [Configuration](../configuration/index.md).
 
-YAML configuration files are reusable and easy to edit. URSA configs can be
-layered; see
-[Configuration files, CLI flags, and environment variables][configuration-files-cli-flags-and-environment-variables]
-for the precedence order.
+## 1. Start URSA
 
-Create `config.yaml`:
-
-```yaml
-llm_model:
-  model: openai:gpt-5.4
-  api_key:
-    env: OPENAI_API_KEY
-workspace: .
-```
-
-Then set your API key in the shell:
+Set your OpenAI API key and launch URSA:
 
 === "macOS/Linux"
 
     ```bash
     export OPENAI_API_KEY="..."
+    ursa
     ```
 
 === "Windows PowerShell"
 
     ```powershell
     $env:OPENAI_API_KEY = "..."
+    ursa
     ```
 
-See [Configuration](../configuration/index.md) for Ollama, Anthropic, Google GenAI, and custom OpenAI-compatible endpoints.
+You should see the full-screen URSA interface. Type `/` to browse app
+commands, `#` to route a message to an agent, or `@` to insert a workspace
+path.
 
-## 2. Start URSA
-
-```bash
-ursa --config config.yaml
-```
-
-You should see the URSA prompt:
-
-```text
-ursa>
-```
+### Full-screen interface controls
 
-Type `help` or `?` inside the prompt to see available interactive commands.
+| Input | Action |
+|---|---|
+| `/` | Browse application commands. Use `/keymap` for every keyboard shortcut. |
+| `#` | Choose an agent and route the message to it. |
+| `@` | Insert a workspace file or directory into the message. |
+| **Enter** | Submit the message. |
+| **Shift+Enter** or **Ctrl+J** | Insert a newline. Some terminals cannot distinguish Shift+Enter, so Ctrl+J is the portable option. |
+| **Ctrl+Q** or `/exit` | Exit gracefully, waiting for an active turn to finish. |
+| **Ctrl+D** | Exit immediately without cleanup; reserve this for a stuck turn. |
 
-## 3. Chat with the assistant
+## 2. Chat with the assistant
 
 ```text
-ursa> Summarize what URSA can help me do.
+Summarize what URSA can help me do.
 ```
 
 Plain text input is handled by the default chat behavior.
 
-## 4. Use the planning agent
+## 3. Route a message to the planning agent
 
-Run the planning agent with the `plan` command:
+Route a message to the planning agent with the `#plan` macro. Typing `#` opens
+the agent picker and inserts the selected agent at the front of the message:
 
 ```text
-ursa> plan Write a plan for building a suite of surrogate models on data.csv and performing assessment of predictive capability and uncertainty quantification.
+#plan Write a plan for building a suite of surrogate models on data.csv and performing assessment of predictive capability and uncertainty quantification.
 ```
 
-You can also type the agent name first and provide the prompt interactively:
+The leading `#` is required; `plan ...` without it is ordinary chat input.
 
-```text
-ursa> plan
-plan: Write a plan for building a suite of surrogate models on data.csv and performing assessment of predictive capability and uncertainty quantification.
-```
-
-## 5. Use the execution agent
+## 4. Route a message to the execution agent
 
 The execution agent can write files and run commands in the configured workspace.
 
 ```text
-ursa> execute Write and run a Python script that prints the first 10 prime numbers.
+#execute Write and run a Python script that prints the first 10 prime numbers.
 ```
 
 Review the actions and outputs carefully. For more safety guidance, see
 [Sandboxing and information control][sandboxing-and-information-control].
 
-## 6. Optional: use a named agent
+To direct the agent to a particular workspace file, type `@` and choose it
+from the path picker:
+
+```text
+#execute Read @data/measurements.csv and create a histogram of the pressure column.
+```
+
+The picker inserts the path into the message; the receiving agent decides how
+to use it and must have an appropriate file tool.
+
+## 5. Optional: use a named agent
 
 A named agent stores state so you can return to it later:
 
 ```bash
-ursa --config config.yaml --name my-first-agent
+ursa --name my-first-agent
 ```
 
 For detailed commands to list, save, copy, share, import, and delete agents, see [Persistence](../persistence/index.md).
 
 ## Useful CLI commands
 
 ```bash
+ursa
 ursa --help
 ursa --print-config
-ursa --config config.yaml
-ursa --config config.yaml --name my-agent
-ursa --config config.yaml --use-web
+ursa --name my-agent
+ursa --use-web
 ```
 
-Web tools are opt in. Use `--use-web` or `use_web: true` only when you want URSA
-to make network requests through its web-search tools.
+Web tools are opt in. Use `--use-web` only when you want URSA to make network
+requests through its web-search tools. Configuration files and their
+`use_web` setting are covered in [Configuration](../configuration/index.md).
 
 ## Where next?
 

diff --git a/docs/index.md b/docs/index.md
@@ -65,11 +65,11 @@ Then run:
 ursa --config config.yaml
 ```
 
-Inside the URSA prompt, type `help` or try:
+Inside the URSA app, type `/` to browse commands or try:
 
 ```text
-ursa> Summarize what URSA can help me do.
-ursa> execute Write and run a Python script that prints the first 10 prime numbers.
+Summarize what URSA can help me do.
+#execute Write and run a Python script that prints the first 10 prime numbers.
 ```
 
 ## Where to go next

diff --git a/docs/reference/tutorials/human-in-the-loop.md b/docs/reference/tutorials/human-in-the-loop.md
diff --git a/examples/hitl_examples/hitl_basic.py b/examples/hitl_examples/hitl_basic.py
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -98,7 +98,6 @@ nav:
       - Plan-Execute checkpointing: reference/plan-execute-checkpointing.md
       - Tutorials and examples:
           - Combining arXiv agent and execution agent: reference/tutorials/arxiv-execution.md
-          - Human in the Loop: reference/tutorials/human-in-the-loop.md
           - Neutron Star: reference/tutorials/neutron-star.md
       - API Reference:
           - agents: reference/api/agents.md