diff --git a/manuals/terminal.md b/manuals/terminal.md
new file mode 100644
index 0000000..ab905ca
--- /dev/null
+++ b/manuals/terminal.md
@@ -0,0 +1,109 @@
+# terminal — Manual
+
+## What it does
+Runs shell commands on the local machine (where Navi's server is running).
+
+The tool supports **two modes**:
+- **One-shot** (`run`) — execute a command and wait for the result. Classic behaviour.
+- **Persistent session** (`open`/`close`/`list`/`status`/`send_input`) — create named terminal sessions that survive across tool calls. Use this for long-running processes (dev servers, build pipelines) or interactive workflows (programs that read stdin).
+
+## Actions
+
+### `run` — one-shot execution
+Run a command and return the full output immediately.
+
+**Parameters:**
+- `action`: `"run"`
+- `command` (string, required) — the shell command
+- `working_dir` (string, optional) — directory to run in
+- `timeout` (integer, optional, default 20, max 300) — seconds to wait
+
+**Example:**
+```json
+{
+  "action": "run",
+  "command": "ls -la",
+  "working_dir": "/home/gmikcon/Projects/navi-1"
+}
+```
+
+### `open` — start a persistent terminal session
+Create a named terminal that keeps running in the background.
+
+**Parameters:**
+- `action`: `"open"`
+- `terminal_name` (string, required) — unique name for this terminal
+- `description` (string, required) — why you opened it (shown in `list`)
+- `command` (string, required) — the command to run
+- `background` (boolean, optional, default false) — if true, returns immediately; if false, waits for completion but still creates a persistent session
+- `working_dir` (string, optional)
+- `timeout` (integer, optional)
+
+**Example — background dev server:**
+```json
+{
+  "action": "open",
+  "terminal_name": "dev_server",
+  "description": "Local HTTP dev server",
+  "command": "python -m http.server 8765",
+  "background": true
+}
+```
+
+**Important:**
+- `terminal_name` must be unique per Navi session. Opening with an existing name will fail.
+- Maximum **10 active terminals per session**.
+- Background terminals are **streamed live** — output appears in the UI as it is produced.
+- Foreground (`background: false`) terminals automatically close after the command finishes.
+
+### `close` — stop a persistent terminal
+Kill the process and remove the session.
+
+**Parameters:**
+- `action`: `"close"`
+- `terminal_name` (string, required)
+
+### `list` — show active terminals
+Returns all running/persistent terminals for the current Navi session with status (busy/idle), PID, and uptime.
+
+**Parameters:**
+- `action`: `"list"`
+
+### `status` — detailed info about one terminal
+Returns command, PID, CWD, uptime, and the last 20 lines of output.
+
+**Parameters:**
+- `action`: `"status"`
+- `terminal_name` (string, required)
+
+### `send_input` — write to a terminal's stdin
+Send text to a background terminal that is waiting for input (e.g. `cat`, `python` REPL, `npm init`).
+
+**Parameters:**
+- `action`: `"send_input"`
+- `terminal_name` (string, required)
+- `input` (string, required) — text to send. Include `\n` for Enter.
+
+**Example:**
+```json
+{
+  "action": "send_input",
+  "terminal_name": "interactive_python",
+  "input": "print(2 + 2)\n"
+}
+```
+
+## When to use persistent sessions instead of `run`
+
+| Situation | Use |
+|---|---|
+| Single command with quick output | `run` |
+| Long-running server or daemon | `open` with `background: true` |
+| Interactive program needing stdin | `open` + `send_input` |
+| Sequence of commands sharing state | Not yet supported (each `open` is a new shell). Use `run` with `;` or write a script. |
+
+## Safety
+- Non-admin users are restricted to a sandbox directory (`user_data/<user_id>/`) and a curated allowlist.
+- Dangerous patterns (curl, wget, ssh, sudo, `python -c`, `node -e`, etc.) are blocked for non-admins.
+- Admins bypass restrictions when `TERMINAL_ALLOWED_COMMANDS=*`.
+- Timeout prevents runaway processes (`run` defaults to 20s; background terminals are cleaned up after 30 min of inactivity).