orrevan 0.1.1 → 0.5.0

package/README.md

@@ -20,25 +20,115 @@ cat log.txt | orrevan -p "what went wrong?"
 orrevan -c                 continue the last conversation in this folder
 orrevan models             list models and prices
 orrevan balance            show your credit
+orrevan whoami             account, credit, model and version
+orrevan update             update to the latest version
+orrevan config             show settings
+orrevan config set model <id>      default model (unset with: orrevan config unset model)
 ```
 
-Options: `-m <model>`, `--plan` (read only), `--yolo` (no approvals, careful).
+Options: `-m <model>`, `--scout` (read only), `--auto` (no approvals, careful), `--web` (allow web search), `--reasoning <level>` (thinking depth: auto, off, low, medium, high, max; which ones depend on the model, see `orrevan models`).
 
-### In the session
+### Modes
 
-| Input | |
+| Mode | |
 |---|---|
+| **Scout** | reads and searches, then proposes a plan. Changes nothing. |
+| **Forge** | edits files and runs commands, shows a diff or the command and asks first. Default. |
+| **Auto** | Forge without asking (`/auto`, `--auto`). Careful. |
+
+`tab` switches between Scout and Forge.
+
+### Type while it works
+
+Keep typing while Orrevan works. `enter` queues the message, Orrevan reads it at its next step (after the current tool) and adjusts. `esc` stops the current answer and sends queued messages right away, so "stop, do this instead" is one keypress.
+
+### Thinking
+
+Reasoning models think before they answer. While they do, the working line shows the latest thought next to the animated Orrevan planet.
+
+- `ctrl+t` shows thoughts in full (live and in the transcript) or collapses them to one line
+- `/thoughts` prints the last thoughts in full
+- `/reasoning` picks the thinking depth (auto, off, low, medium, high, max, as the model offers), `shift+tab` cycles through them. More thinking costs more tokens
+
+### Keys
+
+| Key | |
+|---|---|
+| `?` | all shortcuts (on an empty input) |
+| `ctrl+p` | command palette |
+| `ctrl+x` then a key | leader: `m` model, `r` reasoning, `t` thoughts, `n` new, `s` sessions, `u` undo, `c` compact, `d` diff, `y` copy, `e` export, `w` web, `a` auto, `k` keys, `q` quit |
+| `tab` / `shift+tab` | mode / thinking depth |
+| `@` | attach a file, with completion (`tab`) |
+| `!` | shell mode: run commands yourself, the output goes into the context (`!` or `esc` goes back) |
+| `ctrl+o` | write the message in your editor (`$VISUAL` / `$EDITOR`) |
+| `↑` while working | take the last queued message back to edit it |
+| `esc` | stop |
+| `\` + enter, `ctrl+j` | new line |
+| `ctrl+c` | clear input, stop, twice to quit |
+
+### Commands
+
+| Command | |
+|---|---|
+| `/help` | every command and key |
 | `/model` | switch model (price per 1M tokens shown) |
-| `/plan`, `/build`, `tab` | plan mode is read only, build mode can change things |
+| `/scout`, `/forge`, `/auto` | modes |
+| `/reasoning [level]`, `/thoughts` | thinking depth, last thoughts |
 | `/init` | writes `ORREVAN.md` with notes about the project |
+| `/remember <note>` | adds a note to `ORREVAN.md` |
 | `/compact` | summarises the conversation to save tokens |
-| `/clear`, `/cost`, `/balance`, `/yolo`, `/help`, `/exit` | |
-| `!git status` | run a command yourself, the output goes into the context |
-| `esc` | stop the current answer |
-| `\` + enter | new line |
+| `/undo` | restores the files Orrevan changed in its last turn (shell commands are not undone) |
+| `/diff` | uncommitted changes (`git diff`) |
+| `/copy`, `/export [file]` | copy the last answer, save the conversation as Markdown |
+| `/resume` (`/sessions`) | continue an earlier conversation in this folder |
+| `/title <name>`, `/fork` | name the conversation, branch off into a copy |
+| `/btw <question>` | quick side question on the current context, no tools, not kept. Works while Orrevan works |
+| `/status` | version, model, mode, context, cost, MCP |
+| `/todo` | the task list Orrevan keeps for bigger jobs |
+| `/web` | web search on/off (small fee per search). Once web content is in the conversation, edits and commands need your approval again, even after "always allow" |
+| `/mcp`, `/commands` | connected MCP servers, your own commands |
+| `/clear`, `/cost`, `/balance`, `/exit` | |
+
+Long pastes (over 1000 characters or 15 lines) show as `[Pasted text #1 +40 lines]` and are sent in full.
+
+`@src/app.ts`, `@screenshot.png` sends the file with your message. Images (PNG, JPEG, WebP) need a model with vision. Text files up to 256 KB, images up to 4 MB.
+
+Long conversations are compacted automatically above 100k context tokens (`ORREVAN_AUTO_COMPACT=<tokens>`, `0` turns it off).
+
+### Your own commands
+
+A Markdown file becomes a slash command. Its text is the prompt, `$ARGUMENTS` is what you type after the command (`$1` … `$9` single words).
+
+```
+.orrevan/commands/review.md          this project (can be committed)
+~/.config/orrevan/commands/review.md all your projects
+```
+
+```md
+---
+description: Review a file for bugs
+---
+Review $ARGUMENTS for bugs and risky code. List findings by severity.
+```
+
+Then: `/review src/app.ts`.
+
+### MCP servers
+
+Connect tools over the Model Context Protocol (stdio servers):
+
+```sh
+orrevan mcp add github -e GITHUB_TOKEN=… -- npx -y @modelcontextprotocol/server-github
+orrevan mcp                # list
+orrevan mcp remove github
+```
+
+The config lives in `~/.config/orrevan/mcp.json` (`{"mcpServers": {...}}`, same format as other MCP clients). Only this file is read, never one inside a project, so a cloned repository cannot start programs. Servers start in the background with each session, `/mcp` shows their tools. Every MCP call asks first ("always" allows one server for the session), the Orrevan key is not passed to servers, and their output is treated as untrusted.
 
 ### Tools and approvals
 
+Besides files and commands Orrevan has `todo` (visible task list), `ask_user` (asks you with options when a decision is yours), `task` (a read-only sub-agent with a fresh context for broad searches) and, with `/web` on, `web_search` and `fetch_url` (reads a page, asks first).
+
 Orrevan can `read_file`, `list_dir`, `glob` and `grep` freely inside the project folder. `write_file`, `edit_file` and `run_command` always ask first and show a diff or the command. Answer with *Yes*, *Yes for this session*, or *No* plus what it should do instead.
 
 The tool protocol is plain text, so it works with every model, including uncensored models without native function calling.
@@ -56,6 +146,12 @@ The key is stored in `~/.config/orrevan/config.json` (mode 600). Conversations a
 | `ORREVAN_API_KEY` | key instead of `orrevan login` |
 | `ORREVAN_BASE_URL` | default `https://orrevan.com/api/v1` |
 | `ORREVAN_MODEL` | default model |
+| `ORREVAN_NO_UPDATE_CHECK=1` | no update notice |
+| `ORREVAN_NO_ANIMATION=1` | no logo animation |
+
+### Updates
+
+`orrevan update` installs the newest version from npm (same as `npm install -g orrevan@latest`). In interactive sessions Orrevan checks npm at most once a day and shows a short notice when a newer version exists. The check sends no user data.
 
 ## Development