docs: document non-TUI input and one-shot --message contract

cecli/website/docs/config/tui.md

@@ -5,42 +5,16 @@ description: The TUI (Terminal User Interface) provides a modern, visually rich
 ---
 # TUI
 
-TUI (Terminal User Interface) Mode provides a modern, visually rich terminal interface for AI pair programming.
+TUI (Terminal User Interface) Mode provides a modern, visually rich terminal interface for agentic development and other tasks.
 
 ## Activation
 
-The TUI is the default in recent versions of Cecli and on older versions it can be started explicitly  in the terminal with:
+The TUI is the default in current versions of Cecli and on older versions it can be started explicitly in the terminal with:
 
 ```
 cecli ... --tui
 ```
 
-## Linear terminal mode
-
-For an interactive session without the full-screen TUI, use this canonical
-profile in `~/.cecli/conf.yml` or `.cecli.conf.yml`:
-
-```yaml
-tui: false
-linear-output: true
-fancy-input: true
-stream: true
-```
-
-This keeps the sophisticated `prompt_toolkit` input editor, including history
-and completion, while making output unsophisticated and sequential. Streaming
-responses remain enabled, but Cecli does not redraw earlier application output.
-That linear application-output stream contains no cursor-motion or erasure
-sequences, and a carriage return appears only immediately before a line feed as
-part of a CRLF line ending. The input editor may still use terminal controls
-while editing the current prompt.
-
-This conservative output profile is useful over SSH, in limited terminals, and
-when preserving output in logs or passing it through scripts and pipes. Cecli
-automatically disables fancy input when it detects a dumb terminal. For other
-terminals that cannot reliably support `prompt_toolkit`, set
-`fancy-input: false`.
-
 ## Configuration
 
 The TUI can be configured directly in the relevant config.json file or with JSON in the command line arguments:
@@ -51,18 +25,6 @@ The TUI can be configured directly in the relevant config.json file or with JSON
 tui: true
 ```
 
-### Reduce Motion
-
-Set Textual's native animation level in your shell or `.env` file to keep the
-TUI static while preserving status updates:
-
-```dotenv
-TEXTUAL_ANIMATIONS=none
-```
-
-To hide only the activity spinner, use `--no-spinner` or set `spinner: false`
-in a Cecli configuration file.
-
 ### Complete Configuration Example
 
 The base theme is pretty nice but if you want different colors and key bindings, you can specify them in the configuration files (`~/.cecli/conf.yml` or `.cecli.conf.yml`):
@@ -186,6 +148,32 @@ TUI Mode works seamlessly with other cecli features:
 - **MCP Servers**: Integrated display of MCP tool outputs
 - **Git Operations**: Real-time git status updates in the footer
 
+## Legacy Mode
+
+For an interactive session without the full-screen TUI, use this canonical
+profile in `~/.cecli/conf.yml` or `.cecli.conf.yml`:
+
+```yaml
+tui: false
+linear-output: true
+fancy-input: true
+stream: true
+```
+
+This keeps the sophisticated `prompt_toolkit` input editor, including history
+and completion, while making output unsophisticated and sequential. Streaming
+responses remain enabled, but Cecli does not redraw earlier application output.
+That linear application-output stream contains no cursor-motion or erasure
+sequences, and a carriage return appears only immediately before a line feed as
+part of a CRLF line ending. The input editor may still use terminal controls
+while editing the current prompt.
+
+This conservative output profile is useful over SSH, in limited terminals, and
+when preserving output in logs or passing it through scripts and pipes. Cecli
+automatically disables fancy input when it detects a dumb terminal. For other
+terminals that cannot reliably support `prompt_toolkit`, set
+`fancy-input: false`.
+
 ## Troubleshooting
 
 ### Common Issues
@@ -195,6 +183,18 @@ TUI Mode works seamlessly with other cecli features:
 3. **Performance problems**: Reduce terminal refresh rate or disable animations
 4. **Input lag**: Check for conflicts with terminal multiplexers (tmux, screen)
 
+### Reduce Motion
+
+Set Textual's native animation level in your shell or `.env` file to keep the
+TUI static while preserving status updates:
+
+```dotenv
+TEXTUAL_ANIMATIONS=none
+```
+
+To hide only the activity spinner, use `--no-spinner` or set `spinner: false`
+in a Cecli configuration file.
+
 ### Terminal Requirements
 
 - **True Color Support**: Required for proper color rendering

cecli/website/docs/scripting.md

@@ -24,6 +24,12 @@ for FILE in *.py ; do
 done
 ```
 
+> **Note:** `--message` (`-m`) and `--message-file` (`-f`) are **one-shot**.
+> Cecli sends the message, lets the model act on it, then exits. There is no
+> follow-up prompt in this mode, so an instruction that ends by asking you a
+> question has nowhere to collect your answer. Pass `--yes` for fully
+> non-interactive runs, or use one of the multi-turn routes below.
+
 Use `cecli --help` to see all the [command line options](config/options.html), but these are useful for scripting:
 
 ```
@@ -50,6 +56,23 @@ Use `cecli --help` to see all the [command line options](config/options.html), b
                       [env var: CECLI_COMMIT]
 ```
 
+### Multi-turn input
+
+Run cecli without `--message` and it stays up for a back-and-forth session. Where
+your input comes from depends on the mode:
+
+- **TUI** (`tui: true`, the default): type into the chat input box.
+- **Non-TUI** (`--no-tui`, or `tui: false`): input is read from stdin and
+  re-prompted after every turn. Questions and confirmation prompts from the
+  agent are answered at the terminal prompt.
+- **Programmatic**: an external driver pushes `{"text": ...}` (and
+  `{"confirmed": ...}` for yes/no confirmations) onto the coder's input queue.
+  The [WebSocket/ACP server](config/api.html) and the AgentService wake path use
+  this route.
+
+Both input paths consume the same per-coder queue, so a headless or
+server-driven session can answer prompts with no terminal attached.
+
 
 ## Python